Skip to main content

Model Context Protocol (MCP)

Overview​

Model Context Protocol (MCP) is a mechanism that allows Faheem Code to communicate with external tool servers. These servers can provide additional functionality to the agent, such as specialized data processing, external API access, or custom tools. MCP is based on the open standard defined at modelcontextprotocol.io.

Supported MCPs​

Faheem Code supports the following MCP transport protocols:

How MCP works​

When Faheem Code starts, it:

  1. Reads the MCP configuration.
  2. Connects to any configured SSE and SHTTP servers.
  3. Starts any configured stdio servers.
  4. Registers the tools provided by these servers with the agent.

The agent can then use these tools just like any built-in tool. When the agent calls an MCP tool:

  1. Faheem Code routes the call to the appropriate MCP server.
  2. The server processes the request and returns a response.
  3. Faheem Code converts the response to an observation and presents it to the agent.

Configuration​

MCP configuration can be defined in:

  • The Faheem Code UI in the Settings > MCP page.
  • The config.toml file under the [mcp] section if not using the UI.

Configuration options​

SSE servers are configured using either a string URL or an object with the following properties:

  • url (required)

    • Type: str
    • Description: The URL of the SSE server.

  • api_key (optional)

    • Type: str
    • Description: API key for authentication.

When to use direct stdio​

Direct stdio connections may still be appropriate in these scenarios:

  • Development and testing: Quick prototyping of MCP servers.
  • Simple, single-use tools: Tools that don't require high reliability or concurrent access.
  • Local-only environments: When you don't want to manage additional proxy processes.

Configuration examples​

For stdio-based MCP servers, we recommend using MCP proxy tools like supergateway instead of direct stdio connections. SuperGateway is a popular MCP proxy that converts stdio MCP servers to HTTP/SSE endpoints.

Start the proxy servers separately:

# Terminal 1: Filesystem server proxy
supergateway --stdio "npx @modelcontextprotocol/server-filesystem /" --port 8080

# Terminal 2: Fetch server proxy
supergateway --stdio "uvx mcp-server-fetch" --port 8081

Then configure Faheem Code to use the HTTP endpoint:

[mcp]
# SSE Servers - Recommended approach using proxy tools
sse_servers = [
    # Basic SSE server with just a URL
    "http://example.com:8080/mcp",

    # SuperGateway proxy for fetch server
    "http://localhost:8081/sse",

    # External MCP service with authentication
    {url="https://api.example.com/mcp/sse", api_key="your-api-key"}
]

# SHTTP Servers - Modern streamable HTTP transport (recommended)
shttp_servers = [
    # Basic SHTTP server with default 60s timeout
    "https://api.example.com/mcp/shttp",

    # Server with custom timeout for heavy operations
    {
        url = "https://files.example.com/mcp/shttp",
        api_key = "your-api-key",
        timeout = 1800  # 30 minutes for large file processing
    }
]

Other options include:

  • Custom FastAPI/Express servers: Build your own HTTP wrapper around stdio MCP servers.
  • Docker-based proxies: Containerized solutions for better isolation.
  • Cloud-hosted MCP services: Third-party services that provide MCP endpoints.

Manage installed servers​

In Faheem Code, open Customize > MCP Servers to manage installed MCP servers. Use the control on an installed server card to disable it without deleting its configuration or saved credentials. Disabled servers are unavailable to new conversations until you enable them again.

Adding, editing, renaming, or deleting one server does not remove saved credentials for your other servers. Use the editor's delete action only when you want to remove that server configuration. Editing a disabled server does not enable it.

OAuth authentication​

Some MCP servers (like Notion MCP) require OAuth authentication instead of API keys. Faheem Code supports OAuth-based MCP servers through the FastMCP library.

How OAuth works​

When you configure an OAuth-enabled MCP server:

  1. First connection: When the agent first attempts to use tools from an OAuth-protected MCP server, Faheem Code initiates the OAuth flow
  2. Browser authentication: A browser window opens automatically for you to authorize access
  3. Token storage: After authorization, tokens are securely stored locally in ~/.fastmcp/oauth-mcp-client-cache/
  4. Automatic refresh: FastMCP automatically refreshes tokens as needed

Configuration​

Use the --auth oauth flag when adding an MCP server:

faheemcode mcp add notion --transport http \
  --auth oauth \
  https://mcp.notion.com/mcp

This creates a configuration in ~/.faheem-code/mcp.json:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "transport": "http",
      "auth": "oauth"
    }
  }
}