Integrations

Gestalt still talks about integrations in the API and UI, but config now declares them under providers:. Each configured provider becomes one runtime provider that callers invoke through the shared broker.

Provider Shape

providers:
  gmail:
    display_name: Gmail
    description: Read and send Gmail messages
    from:
      package: ./dist/gmail-plugin.tar.gz
    mcp:
      enabled: true
      tool_prefix: gmail_

Each entry can combine:

an optional from block for executable or packaged behavior
connections
one API surface under surfaces.rest, surfaces.openapi, or surfaces.graphql
an optional surfaces.mcp
optional headers, managed_parameters, response_mapping, and allowed_operations

The Four Main Patterns

Pattern	Use it for
Inline declarative provider	Small custom REST APIs where writing a binary would be overkill.
Inline spec-backed provider	OpenAPI, GraphQL, or upstream MCP surfaces that Gestalt can load directly.
Packaged provider plugin	Custom logic that belongs in code or ships as a reusable package.
Hybrid provider	A packaged plugin combined with OpenAPI, GraphQL, or MCP surfaces.

Inline Declarative Providers

Inline declarative providers use surfaces.rest.

providers:
  support:
    connections:
      default:
        auth:
          type: bearer
          credentials:
            - name: token
              label: API Token
    surfaces:
      rest:
        base_url: https://api.support.example.com
        operations:
          - name: list_tickets
            description: Return open support tickets
            method: GET
            path: /tickets

This is the simplest path when you already know the exact operations you want.

Inline Spec-Backed Providers

Inline spec-backed providers load operations from OpenAPI, GraphQL, or upstream MCP.

providers:
  httpbin:
    connections:
      public:
        mode: none
        auth:
          type: none
    surfaces:
      openapi:
        document: ./openapi/httpbin.yaml
        connection: public
    allowed_operations:
      get_ip:
        alias: get_ip
    mcp:
      enabled: true
      tool_prefix: httpbin_

allowed_operations narrows the exposed surface and can rename operations with alias.

Packaged Provider Plugins

Packaged providers come from one of three sources:

command: run an executable directly
package: load a local directory, local archive, or HTTPS archive
source plus version: resolve a published plugin package during init

providers:
  support:
    display_name: Support
    from:
      package: ./dist/support-plugin.tar.gz

Packaged providers carry their own manifests, auth model, and operation catalog.

Hybrid Providers

A packaged provider can also layer in spec-backed surfaces.

providers:
  support:
    display_name: Support
    from:
      package: ./dist/support-plugin.tar.gz
    connections:
      mcp:
        mode: user
        auth:
          type: mcp_oauth
    surfaces:
      openapi:
        document: ./openapi/support.yaml
      mcp:
        url: https://mcp.support.example.com/mcp
        connection: mcp
    allowed_operations:
      tickets.list:
        alias: list_tickets
    mcp:
      enabled: true
      tool_prefix: support_

This is useful when a plugin provides custom code while the API or MCP surface still comes from a spec or upstream server.

Connections

Gestalt resolves credentials through connections.default plus any optional named connections.

connections:
  default:
    mode: user
    auth:
      type: oauth2
      authorization_url: https://accounts.example.com/oauth/authorize
      token_url: https://accounts.example.com/oauth/token
      client_id: ${CLIENT_ID}
      client_secret: ${CLIENT_SECRET}
    params:
      tenant:
        required: true
  mcp:
    mode: user
    auth:
      type: mcp_oauth

Rules:

connections.default is the primary connection
only connections.default may define params and discovery
if you omit connections.default and keep only named connections, each configured surface must set connection

Connection Modes

Mode	Meaning
`none`	No stored credential is needed.
`user`	Use a user-scoped stored connection.
`identity`	Use a shared service identity.
`either`	Prefer user auth and fall back to the shared identity.

Managed Parameters

managed_parameters inject fixed values into headers or path placeholders before an operation is exposed.

providers:
  workspace:
    connections:
      default:
        mode: none
        auth:
          type: none
    surfaces:
      openapi:
        document: ./openapi/workspace.yaml
    managed_parameters:
      - in: header
        name: X-API-Version
        value: "2026-04-01"
      - in: path
        name: account_id
        value: primary

Path managed parameters remove the corresponding user parameter from the exposed operation signature.

Response Mapping

response_mapping is available for OpenAPI and GraphQL providers when the upstream response needs a stable data path or pagination hints.

providers:
  catalog:
    connections:
      default:
        auth:
          type: bearer
    surfaces:
      graphql:
        url: https://api.example.com/graphql
    response_mapping:
      data_path: data.items
      pagination:
        has_more_path: pageInfo.hasNextPage
        cursor_path: pageInfo.endCursor

Tool Naming On `/mcp`

Use mcp.tool_prefix to keep tool names stable and collision-free when several providers expose operations with similar names.

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

Choosing The Right Pattern

Start with inline declarative YAML for a tiny REST surface.
Use OpenAPI, GraphQL, or surfaces.mcp when the upstream already publishes a discoverable surface.
Use packaged providers when behavior belongs in code or needs to be versioned.
Use a hybrid provider when you want packaged logic plus spec-backed coverage.

Configuration Authentication And Tokens