API: MCP Servers

Manage Model Context Protocol (MCP) server connections for your organization.

List MCP Servers

GET /api/mcps

List all MCP servers configured for your organization.

curl https://api.flapjack.dev/api/mcps \
  -H "Authorization: Bearer fj_live_..."

Response 200:

[
  {
    "id": "mcp-001",
    "name": "GitHub",
    "slug": "github",
    "transport": "streamable_http",
    "url": "https://mcp.github.com/sse",
    "status": "active",
    "hasCredentials": true,
    "toolsCache": [
      { "name": "list_repos", "description": "List repositories" }
    ],
    "createdAt": "2026-03-28T12:00:00Z"
  }
]

Note: Response uses camelCase field names. Encrypted credentials are never returned — only hasCredentials: boolean indicates whether credentials exist.

📋 Copy as prompt

List all MCP servers in my Flapjack organization using curl on /api/mcps.

---

Create MCP Server

POST /api/mcps

Add a new MCP server connection.

Request body:

Field	Type	Required	Description
name	string	Yes	Display name
transport	string	Yes	streamable_http, sse, or stdio
url	string	Conditional	Server URL (required for streamable_http and sse)
command	string	Conditional	Subprocess command (required for stdio)
args	string[]	No	Subprocess arguments (for stdio)
credentials	object	No	Encrypted credentials (see below)
credentials.headers	object	No	HTTP headers (encrypted at rest)
credentials.env	object	No	Environment variables (encrypted at rest)
allowedTools	string[]	No	Restrict to specific tools

Note: slug is auto-derived from name — do not provide it.

curl -X POST https://api.flapjack.dev/api/mcps \
  -H "Authorization: Bearer fj_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub",
    "transport": "streamable_http",
    "url": "https://mcp.github.com/sse",
    "credentials": {
      "headers": { "Authorization": "Bearer ghp_..." }
    }
  }'

Response 201: The created MCP server object.

📋 Copy as prompt

Add a GitHub MCP server to my Flapjack organization using the API. POST to /api/mcps with name, slug, transport type, URL, and authorization header.

---

Get MCP Server

GET /api/mcps/{mcpId}

Get details of a specific MCP server.

---

Update MCP Server

PATCH /api/mcps/{mcpId}

Update an MCP server's configuration.

---

Delete MCP Server

DELETE /api/mcps/{mcpId}

Delete an MCP server and all agent attachments.

---

Test MCP Connection

POST /api/mcps/{mcpId}/test

Test the connection to an MCP server and discover available tools.

curl -X POST https://api.flapjack.dev/api/mcps/mcp-001/test \
  -H "Authorization: Bearer fj_live_..."

Response 200:

{
  "ok": true,
  "tools": [
    { "name": "list_repos", "description": "List repositories", "inputSchema": {} },
    { "name": "create_issue", "description": "Create a GitHub issue", "inputSchema": {} }
  ]
}

---

OAuth Flow

For MCP servers that require OAuth authentication:

Start OAuth

POST /api/mcps/{mcpId}/oauth/start

Initiates the OAuth 2.1 authorization flow. Returns a redirect URL.

OAuth Callback

GET /api/mcps/{mcpId}/oauth/callback

Handles the OAuth callback and stores encrypted tokens.

---

Attach MCP to Agent

POST /api/agents/{agentId}/mcps

Request body:

Field	Type	Required	Description
mcpServerId	string	Yes	MCP server UUID
allowedTools	string[]	No	Per-agent tool filter

Attach MCP to Runner

POST /api/runners/{runnerId}/mcps

Same request body as agent attachment. Runner-level MCPs serve as defaults for all steps. See API: Runners for details.

---

Search MCP Registry

GET /api/mcp-registry/search?q={query}

Search the official MCP registry for available servers.

curl "https://api.flapjack.dev/api/mcp-registry/search?q=github" \
  -H "Authorization: Bearer fj_live_..."

Next Steps

• MCP: Overview — what MCP is and how it works
• MCP: Connecting — step-by-step connection guide
• MCP: OAuth — OAuth flow for authenticated servers