MCP Servers

Every Keel project exposes an MCP (opens in a new tab) (Model Context Protocol) server. This lets AI assistants like Claude, ChatGPT, and Cursor discover your data model and execute actions — without writing any integration code.

Endpoint

Keel exposes an MCP server for each API defined in your schema. The endpoint follows the pattern /{apiName}/mcp and speaks MCP's Streamable HTTP transport (JSON-RPC 2.0 over HTTP).

For example, given this schema:

api Web {
    models {
        Product
        Order
    }
}
 
api Internal {
    models {
        AuditLog
    }
}

Two MCP endpoints are available:

https://your-app.keelapps.xyz/web/mcp
https://your-app.keelapps.xyz/internal/mcp

If you don't define any APIs in your schema, Keel creates a default API called api, and the MCP endpoint is:

https://your-app.keelapps.xyz/api/mcp

Each MCP server only exposes the models and actions belonging to its API, so you can control what each AI assistant has access to by scoping a dedicated api block to it.

What's included

Rather than turning every action into its own MCP tool, Keel exposes a small, fixed set of tools that let an AI assistant explore your schema and then call any action through a uniform interface:

Tool	Description
`list_actions`	Returns a compact list of available actions with their name, model, type, and required/optional inputs.
`describe_action`	Given an action name, returns its full input/output JSON schema and a usage example.
`query`	Executes a read action (`get`, `list`, or `read`) by name with JSON input.
`mutate`	Executes a write action (`create`, `update`, `delete`, or `write`) by name with JSON input.

This means you don't need to add or remove anything to control what's exposed over MCP — the tools automatically reflect whatever models and actions are included in that API's models block, the same scope used for its GraphQL, JSON, and JSON-RPC endpoints. A well-behaved assistant typically calls list_actions first to understand your data model, then describe_action before calling query or mutate.

Connecting AI tools

Claude Desktop

Open your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add your Keel MCP server:

{
  "mcpServers": {
    "my-keel-app": {
      "url": "https://your-app.keelapps.xyz/web/mcp"
    }
  }
}

Restart Claude Desktop. On the first message, Claude will walk you through authenticating with your Keel app in the browser.

Claude Code

Add the MCP server using the Claude Code CLI:

claude mcp add my-keel-app --transport http https://your-app.keelapps.xyz/web/mcp

Claude Code will handle OAuth authentication automatically when you first interact with the server.

Claude Team & Enterprise

On Team and Enterprise plans, an organization owner can add your Keel MCP server as a custom connector (opens in a new tab) from Settings → Connectors on claude.ai. Once added, it's available to your team across claude.ai, Claude Desktop, and the mobile apps — see Anthropic's guide to building custom connectors via remote MCP servers (opens in a new tab) for setup details.

ChatGPT

ChatGPT supports remote MCP servers via connectors and apps (opens in a new tab) on Plus, Pro, Team, Enterprise, and Edu plans. See OpenAI's developer mode and MCP apps guide (opens in a new tab) for how to add your Keel MCP server URL as a connector. ChatGPT will prompt you to complete the OAuth flow the first time you use it in a conversation.

Cursor

Open Cursor's MCP configuration file at ~/.cursor/mcp.json (or .cursor/mcp.json in your project root for project-scoped servers) and add:

{
  "mcpServers": {
    "my-keel-app": {
      "url": "https://your-app.keelapps.xyz/web/mcp"
    }
  }
}

Restart Cursor. The MCP server will appear in Cursor's tool list, and authentication will be handled when you first use it.

Windsurf

Open Windsurf's MCP configuration file at ~/.codeium/windsurf/mcp_config.json and add:

{
  "mcpServers": {
    "my-keel-app": {
      "serverUrl": "https://your-app.keelapps.xyz/web/mcp"
    }
  }
}

Refresh the MCP server list from Windsurf Settings → MCP Servers. Windsurf will handle OAuth authentication on first use.

VS Code (GitHub Copilot)

Add the MCP server using the VS Code CLI:

code --add-mcp '{"name":"my-keel-app","url":"https://your-app.keelapps.xyz/web/mcp"}'

Or add it to your workspace .vscode/mcp.json:

{
  "servers": {
    "my-keel-app": {
      "url": "https://your-app.keelapps.xyz/web/mcp"
    }
  }
}

VS Code will prompt you to sign in via OAuth the first time Copilot uses the server.

OpenAI Codex CLI

Add the MCP server using the Codex CLI:

codex --mcp-config '{"my-keel-app": {"url": "https://your-app.keelapps.xyz/web/mcp"}}'

Or add it to your ~/.codex/config.yaml for persistent configuration:

mcpServers:
  my-keel-app:
    url: https://your-app.keelapps.xyz/web/mcp

Codex will handle OAuth authentication automatically on first use.

Gemini CLI

Add the MCP server to your ~/.gemini/settings.json (or .gemini/settings.json in your project root):

{
  "mcpServers": {
    "my-keel-app": {
      "httpUrl": "https://your-app.keelapps.xyz/web/mcp"
    }
  }
}

Gemini CLI will handle OAuth authentication automatically on first use.

Authentication

Your Keel app must have at least one authentication provider configured for MCP authentication to work. MCP clients handle the OAuth flow automatically — a browser window will open for you to log in on first use.

Under the hood, each request to an MCP endpoint requires a valid Keel access token in the Authorization header, exactly like the GraphQL, JSON, and JSON-RPC APIs. If the token is missing or invalid, Keel returns a 401 response with a WWW-Authenticate header pointing MCP clients to the app's OAuth metadata, so compliant clients can discover and complete the login flow automatically.

Local development

When running your Keel app locally with keel run, you can connect AI tools to your local MCP server:

{
  "mcpServers": {
    "my-keel-app-local": {
      "url": "http://localhost:8000/api/mcp"
    }
  }
}

The MCP server's OAuth authentication flow requires an SSO authentication provider (such as Google or Auth0) to be configured. If you don't have an SSO provider set up locally, you can authenticate manually by generating a bearer token and passing it in the MCP server configuration as a header:

{
  "mcpServers": {
    "my-keel-app-local": {
      "url": "http://localhost:8000/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

If your actions allow public access, no authentication is needed.

Example

Given a Keel schema like this:

model Product {
    fields {
        name Text
        price Number
        inStock Boolean
    }
 
    actions {
        list listProducts()
        create createProduct() with (name, price, inStock)
    }
}

An AI assistant connected to your MCP server can handle natural language requests such as:

"Show me all products that are in stock" — the assistant calls list_actions to learn about listProducts, then calls query with {"action": "listProducts", "input": {"where": {"inStock": {"equals": true}}}}
"Add a new product called Widget for $9.99" — the assistant calls describe_action for createProduct to confirm the input shape, then calls mutate with {"action": "createProduct", "input": {"name": "Widget", "price": 9.99, "inStock": true}}

JSON API keelconfig.yaml