MCP: Connecting Servers

Add MCP servers to your Flapjack organization, then attach them to agents.

Via Dashboard

1. Go to MCP Servers in the sidebar
2. Click Add Server
3. Search the registry or enter a custom URL
4. Configure credentials (API key, OAuth, or environment variables)
5. Test the connection
6. Attach to one or more agents

Via API

Step 1: Create the MCP Server

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_your_github_token" }
    }
  }'

Note: slug is auto-derived from the name. Credentials are encrypted at rest.

📋 Copy as prompt

Add a GitHub MCP server to my Flapjack organization. POST to /api/mcps with the name "GitHub", streamable_http transport, the GitHub MCP URL, and my GitHub token under credentials.headers.

Step 2: Test the Connection

curl -X POST https://api.flapjack.dev/api/mcps/{mcpId}/test \
  -H "Authorization: Bearer fj_live_..."

This connects to the server, runs tools/list, and returns available tools:

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

Step 3: Attach to an Agent

curl -X POST https://api.flapjack.dev/api/agents/{agentId}/mcps \
  -H "Authorization: Bearer fj_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mcpServerId": "mcp-001",
    "allowedTools": ["list_repos", "create_issue"]
  }'

The allowedTools field is optional. If omitted, all tools from the server are available.

📋 Copy as prompt

Attach my GitHub MCP server to a Flapjack agent. POST to /api/agents/{agentId}/mcps with the MCP server ID and optionally filter which tools the agent can use.

Transport Configuration

HTTP (streamable_http)

Most common for remote MCP servers:

{
  "transport": "streamable_http",
  "url": "https://mcp-server.example.com/mcp",
  "credentials": {
    "headers": { "Authorization": "Bearer ..." }
  }
}

Requirements: URL must be HTTPS. Private IPs and localhost are blocked.

SSE (Server-Sent Events)

Legacy transport for older MCP servers:

{
  "transport": "sse",
  "url": "https://mcp-server.example.com/sse"
}

stdio (Subprocess)

For local command-line MCP tools:

{
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"]
}

Searching the Registry

Find MCP servers from the official registry:

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

Tool Filtering

Filter tools at two levels:

1. Server level (allowedTools on the MCP server) — restricts which tools are available org-wide
2. Agent level (allowedTools when attaching) — restricts per-agent

Credential Security

• All credentials are encrypted with AES-256-GCM before storage
• Headers and environment variables are never returned in API responses
• OAuth tokens are automatically refreshed 2 minutes before expiry

Next Steps

• MCP: OAuth — for servers requiring OAuth
• MCP: Building Tools — create your own MCP server
• API: MCP Servers — full endpoint reference