Skip to main content

MCP servers

Overview​

Model Context Protocol (MCP) servers provide additional tools and context to Faheem Code agents. You can add HTTP/SSE servers with authentication or stdio-based local servers to extend what Faheem Code can do.

The CLI provides two ways to manage MCP servers:

  1. CLI commands (faheemcode mcp) - Manage servers from the command line
  2. Interactive command (/mcp) - View server status within a conversation

MCP commands​

List servers​

View all configured MCP servers:

faheemcode mcp list

Get server details​

View details for a specific server:

faheemcode mcp get <server-name>

Remove a server​

Remove a server configuration:

faheemcode mcp remove <server-name>

Enable/Disable servers​

Control which servers are active:

# Enable a server
faheemcode mcp enable <server-name>

# Disable a server
faheemcode mcp disable <server-name>

Adding servers​

HTTP/SSE servers​

Add remote servers with HTTP or SSE transport:

faheemcode mcp add <name> --transport http <url>

With Bearer token authentication​

faheemcode mcp add my-api --transport http \
  --header "Authorization: Bearer your-token" \
  https://api.example.com/mcp

With API key authentication​

faheemcode mcp add weather-api --transport http \
  --header "X-API-Key: your-api-key" \
  https://weather.api.com

With multiple headers​

faheemcode mcp add secure-api --transport http \
  --header "Authorization: Bearer token123" \
  --header "X-Client-ID: client456" \
  https://api.example.com

With OAuth authentication​

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

Stdio servers​

Add local servers that communicate via stdio:

faheemcode mcp add <name> --transport stdio <command> -- [args...]

Basic example​

faheemcode mcp add local-server --transport stdio \
  python -- -m my_mcp_server

With environment variables​

faheemcode mcp add local-server --transport stdio \
  --env "API_KEY=secret123" \
  --env "DATABASE_URL=postgresql://localhost/mydb" \
  python -- -m my_mcp_server --config config.json

Add in disabled state​

faheemcode mcp add my-server --transport stdio --disabled \
  node -- my-server.js

Command reference​

faheemcode mcp add <name> --transport <type> [options] <target> [-- args...]
OptionDescription
--transportTransport type: http, sse, or stdio (required)
--headerHTTP header for http/sse (format: "Key: Value", repeatable)
--envEnvironment variable for stdio (format: KEY=value, repeatable)
--authAuthentication method (e.g., oauth)
--enabledEnable immediately (default)
--disabledAdd in disabled state

Example: web search with Tavily​

Add web search capability using Tavily's MCP server:

faheemcode mcp add tavily --transport stdio \
  npx -- -y mcp-remote "https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>"

Manual configuration​

You can also manually edit the MCP configuration file at ~/.faheem-code/mcp.json.

Configuration format​

The file uses the MCP configuration format:

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Example configuration​

{
  "mcpServers": {
    "tavily-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.tavily.com/mcp/?tavilyApiKey=your-api-key"
      ]
    },
    "local-tools": {
      "command": "python",
      "args": ["-m", "my_mcp_tools"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

Interactive /mcp command​

Within an Faheem Code conversation, use /mcp to view server status:

  • View active servers: Shows which MCP servers are currently active in the conversation
  • View pending changes: If mcp.json has been modified, shows which servers will be mounted when the conversation restarts

Workflow​

  1. Add servers using faheemcode mcp add
  2. Start a conversation with faheemcode
  3. Check status with /mcp inside the conversation
  4. Use the tools provided by your MCP servers

The agent will automatically have access to tools provided by enabled MCP servers.

Troubleshooting​

Server not appearing​

  1. Verify the server is enabled:

    faheemcode mcp list

  2. Check the configuration:

    faheemcode mcp get <server-name>

  3. Restart the conversation to load new configurations

Server fails to start​

  1. Test the command manually:

    # For stdio servers
    python -m my_mcp_server

    # For HTTP servers, check the URL is reachable
    curl https://api.example.com/mcp

  2. Check environment variables and credentials

  3. Review error messages in the CLI output

Configuration file location​

The MCP configuration is stored at:

  • Config file: ~/.faheem-code/mcp.json

See also​