MCP Server Integration

The Model Context Protocol (MCP) is an open standard for exposing tools and data to LLMs. Pipelines connects to remote MCP servers and makes their tools available to LLM-generated pipeline fields.

Three ways to connect an MCP server

1. Provider gallery — one-click tiles on the MCP Servers page. Each tile knows the URL and the right auth flow for that vendor.
2. Add Tool Endpoint → MCP Server tab — use this for internal MCP servers or vendors not in the gallery.
3. Deconstruct a vendor JSON snippet — many vendors publish a mcpServers JSON blob intended for Claude Desktop. Pipelines doesn't import this directly, but the fields are easy to map into the modal. See When the vendor gives you a JSON snippet below.

Provider gallery

These providers are pre-configured. On the MCP Servers page, scroll to the gallery and click Connect on the tile you want.

Register a custom MCP server

1. Navigate to MCP Servers in the sidebar.
2. Click Add Tool Endpoint.
3. Make sure the MCP Server tab is selected.
4. Fill in the fields:
   • Name (required) — how the endpoint is displayed in lists and the Pipeline Builder (1–255 characters).
   • URL (required) — the Streamable HTTP endpoint URL. Must use https://, for example https://mcp.example.com/mcp.
   • Description (optional) — short note for teammates.
   • Authentication method — one of:
     • None — no auth headers.
     • API Key — a single custom header. Fill in Header Name (default X-API-Key) and the key value.
     • Bearer Token — sent as Authorization: Bearer <token>.
     • OAuth 2.0 — opens a consent popup. See OAuth for Tools.
5. Click Add & Discover Tools (or Connect via OAuth for OAuth servers).

What happens on save. Pipelines connects to the server (running OAuth discovery if OAuth was selected), asks it for its tool list, and stores each discovered tool on the endpoint. If the server is unreachable, the endpoint is still saved with status unhealthy so you can retry with Refresh Tools later.

When the vendor gives you a JSON snippet

MCP vendors commonly publish a config like:

{
  "mcpServers": {
    "example": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer sk-..." }
    }
  }
}

Pipelines doesn't accept this file directly. Deconstruct it into the modal like so:

If the snippet only has url and no headers, pick Authentication: None. If it has both an Authorization header and a second custom header, the UI only supports one — use whichever carries the credential.

Tool discovery

After saving, discovered tools appear on the endpoint detail page with name, description, and input schema. This list is read-only — you can't disable tools at the endpoint level. To restrict which tools an LLM can actually call, do it per binding (pick Specific tools instead of All tools when attaching the endpoint to a field). See Tool Bindings.

Click Refresh Tools on the detail page to re-ask the server for its tool list. All previously stored tool records are replaced with the fresh set.

Health status and Test Connection

Every endpoint shows one of three health states as a badge on the list and detail pages:

Health is not continuously monitored. It's only updated when you click Test Connection or Refresh Tools, when you first create the endpoint, or at the end of an OAuth callback. There is no background sweep.

Test Connection re-runs initialize and tools/list against the server. For OAuth endpoints, it also refreshes the access token if it's close to expiry. The result shows the tool count detected and, on failure, the server's error message.

Using MCP tools in pipelines

1. Open a pipeline in the Pipeline Builder.
2. Select a node and click an LLM-response field.
3. In the LLM configuration panel, open Tool Bindings → Add Tool Binding.
4. Pick the MCP endpoint, then either leave "all tools" selected or pick specific tools.
5. Optionally set Max Tool Rounds (default 5, up to 20).
6. Save.

See Tool Bindings for how bindings behave during generation.

Debugging checklist

If tool calls aren't working as expected:

1. On the endpoint detail page, click Test Connection. The error message is shown verbatim.
2. Click Refresh Tools. If the expected tool isn't listed, the problem is upstream on the MCP server.
3. Confirm the endpoint is Active (toggle on the list page).
4. For OAuth endpoints with a stale token, re-run the OAuth flow from the detail page.
5. Check the binding still targets the tool you expect. When multiple endpoints expose a tool with the same name, Pipelines auto-prefixes them with a sanitized endpoint name to disambiguate.
6. In Data Explorer, open a recent run and inspect per-round tool calls — the arguments, result (truncated at 100 KB), and any error are recorded against the LLM response.

Further reading

• MCP spec
• Reference MCP servers (GitHub)
• MCP authorization spec (OAuth 2.1 + PKCE + DCR)