Skip to main content
PromptLayer-managed MCP servers let you connect a remote Model Context Protocol server once and reuse it across prompts. PromptLayer discovers the server’s tools, presents them to the selected model provider, executes tool calls, and returns the results to the model. Because the connection is managed by PromptLayer, the same saved MCP server can be used with supported providers and API types instead of depending on provider-native MCP support.

​
Create an MCP server

  1. Open Settings.
  2. Under Workspace, select MCP Servers.
  3. Click New MCP Server.
  4. Enter a name, optional description, and the HTTPS URL exposed by the MCP server.
  5. Add any authentication headers the server requires.
  6. Click Test Connection to discover the available tools.
  7. Optionally choose which discovered tools prompts can use.
  8. Save the server.
MCP Servers settings page
Use a name that identifies the service or purpose, such as GitHub, Support Docs, or Internal Search. This name appears when users add the server to a prompt.

​
Configure authentication securely

Header values must reference encrypted workspace environment variables. This keeps credentials out of prompt definitions and prevents users from accidentally saving raw tokens in an MCP configuration. Create the required secret under Settings → Environment Variables, then map each header to its environment variable when configuring the MCP server. For example, an Authorization header can reference an environment variable whose value includes the complete authorization value expected by the server.
MCP server authentication header mapped to an environment variable
Do not paste API keys or access tokens directly into header fields. Store them as workspace environment variables first.

​
Test the connection

Test Connection connects to the server and lists the tools it exposes. Use this before saving to confirm that:
  • The server URL is reachable.
  • Authentication headers are correct.
  • Tool names, descriptions, and input schemas are available.
  • The server exposes the tools you expect.
You can restrict the connection to selected tools. If no tools are selected, all tools discovered from the server are available to linked prompts.
Discovered tools from a successful MCP server connection test

​
Add an MCP server to a prompt

  1. Open a chat prompt in the Playground.
  2. Open the Tool & Output Editor.
  3. Click Add Tool → MCP Server.
  4. Search for the saved server.
  5. Select it to add the reference to the prompt.
The prompt displays the saved server’s name instead of a generic MCP label.
MCP Server picker in the Tool and Output Editor

​
How saved references work

A prompt stores a lightweight reference to the saved MCP server:
PromptLayer resolves the current server configuration when the prompt runs. Editing the URL, headers, or allowed tools updates every linked prompt automatically; you do not need to create new prompt versions just to receive the MCP configuration change.
MCP server configurations use live, mutable references. This differs from versioned Tool Registry references and prompt versions.
An MCP server cannot be deleted while prompt versions still reference it. Remove the server from those prompts and save new prompt versions before deleting the connection.

​
Run with different providers

PromptLayer discovers each MCP capability and translates it into the function-tool format required by the selected provider. When the model calls one of those tools, PromptLayer executes it against the MCP server, sends the result back to the model, and continues the tool-calling loop. This managed path works independently of whether the provider offers its own native MCP tool type.

​
PromptLayer-managed versus provider-native MCP

PromptLayer-managed MCP and provider-native MCP are separate options: Existing OpenAI-native MCP tools remain available under Built-In Tool. They are not converted into PromptLayer-managed MCP server references.