Add An Integration

Choose the integration style that matches the upstream.

Inline Declarative YAML

Use this when the surface is small and custom.

integrations:
  support:
    display_name: Support
    plugin:
      auth:
        type: bearer
        credentials:
          - name: token
            label: API Token
      base_url: https://api.support.example.com
      operations:
        - name: list_tickets
          method: GET
          path: /tickets

Inline OpenAPI

Use this when the upstream already publishes a spec.

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

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

Packaged Plugin

Use this when the logic belongs in code or should be versioned independently.

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

Prepare it and start from locked state:

gestaltd init --config ./config.yaml
gestaltd serve --locked --config ./config.yaml

Hybrid Provider

Use this when you want packaged custom logic plus spec-backed operations.

Assume you already have a local package such as ./dist/support-plugin.tar.gz and a local OpenAPI file such as ./openapi/support.yaml.

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

Named Connections

Use named connections when different surfaces need different auth flows.

integrations:
  workspace:
    plugin:
      openapi: ./openapi/workspace.yaml
      mcp_url: https://mcp.example.com/mcp
      openapi_connection: api
      mcp_connection: mcp
      default_connection: api
      connections:
        api:
          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}
        mcp:
          mode: user
          auth:
            type: mcp_oauth

Validate The Result

gestaltd validate --init --config ./config.yaml

That catches:

invalid YAML
undeclared named connections
invalid manifest references
stale packaged plugin state

Run Locally Use With MCP