MCP

Gestalt exposes one MCP endpoint at /mcp.

When /mcp Exists

The endpoint is mounted when at least one integration declares an MCP-capable surface. In practice that includes:

• inline declarative operations
• OpenAPI-backed integrations
• GraphQL-backed integrations
• integrations with mcp_url
• packaged providers whose catalog should be available through MCP

How Tool Discovery Works

Gestalt turns provider catalogs into MCP tools.

• HTTP-backed operations become normal tools that route through the invocation broker.
• Upstream MCP tools can be passed through directly.
• Hybrid providers expose both sets in one integration catalog.

If a provider supports request-scoped catalogs, Gestalt refreshes those tools at MCP list or call time so the tool surface reflects the caller’s current connection.

Tool Naming

Tool names come from the provider operation IDs. Use mcp.tool_prefix on a provider to keep names stable across providers.

providers:
  slack:
    mcp:
      enabled: true
      tool_prefix: slack_

Authentication

/mcp uses the same auth middleware as the rest of the authenticated API.

Callers can authenticate with:

• a platform session cookie
• Authorization: Bearer <gst_api_...>

The endpoint does not have a separate auth model.

Connection Selection

The same connection logic used by the HTTP API also applies to MCP:

• the server resolves the integration’s default connection
• surface-specific connection names are honored
• if there are multiple stored instances and no unique match, the call fails

For hybrid providers this means the API-backed and MCP-backed parts of the same integration can use different named connections.

Example

Assume you already have a local OpenAPI file such as ./openapi/notion.yaml.

providers:
  notion:
    mcp:
      enabled: true
      tool_prefix: notion_
    surfaces:
      openapi:
        document: ./openapi/notion.yaml
        connection: REST
      mcp:
        url: https://mcp.notion.com/mcp
        connection: MCP
    connections:
      MCP:
        mode: user
        auth:
          type: mcp_oauth
      REST:
        mode: user
        auth:
          type: bearer
          credentials:
            - name: token
              label: API Token

With this config:

• the HTTP API exposes the OpenAPI-backed operations
• /mcp exposes the same REST operations plus the upstream Notion MCP tools
• the upstream MCP tools authenticate through the MCP named connection