◆Franklin/Docs

MCP Integration

Connect external tools via Model Context Protocol servers.

What is MCP?

The Model Context Protocol (MCP)is an open standard for connecting AI agents to external tools and data sources. Franklin supports MCP natively — any MCP server can be plugged in as a tool provider.

Server Discovery

Franklin discovers MCP servers from three locations, checked in order. Later sources override earlier ones:

  1. Built-in — the blockrunMCP server ships with Franklin and provides access to BlockRun's API gateway (search, wallet, markets, models).
  2. Global — ~/.blockrun/mcp.json. Servers defined here are available in every project.
  3. Project — .mcp.json in the project root. Scoped to the current project only.

Configuration Format

Both ~/.blockrun/mcp.json and .mcp.json use the same format:

json
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

Transports

stdio (default)

The most common transport. Franklin spawns the MCP server as a child process and communicates over stdin/stdout.

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
    }
  }
}

HTTP (SSE)

For remote MCP servers, use HTTP with Server-Sent Events. Specify a url instead of command:

json
{
  "mcpServers": {
    "remote-tools": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Auto-wrapping

MCP tools are automatically wrapped as CapabilityHandlers. The agent sees them alongside built-in tools with no extra configuration. Tool names are prefixed with the server name (e.g., mcp__filesystem__read_file).

Using MCP Tools

Once configured, MCP tools are immediately available. The agent discovers them on startup and can call them like any built-in tool. To see which MCP servers are connected:

bash
# Inside a Franklin session
/mcp

This lists all connected MCP servers and their available tools.

Example: Adding a Database Server

Add a PostgreSQL MCP server so Franklin can query your database:

json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Save this to .mcp.json in your project root, then restart Franklin. The agent can now run SQL queries through the postgres tools.