Configuring Agents as MCP Clients

Claude Code, Codex, and OpenCode are all MCP clients. Your job is to tell each one which servers to connect to and how.

How Code Agents Act as MCP Clients

Once an MCP server is configured, the agent connects to it, discovers which tools and resources it exposes, and treats them like built-in capabilities. The agent’s MCP client handles discovery, request routing, and errors behind the scenes.

Adding an MCP Server

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

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

# Local Python server
claude mcp add --transport stdio calculator -- python /path/to/server.py

# Remote HTTP server
claude mcp add --transport http my-api https://api.example.com/mcp

# With scope and env vars
claude mcp add --transport stdio --scope user --env API_KEY=xxx github -- npx -y @modelcontextprotocol/server-github

Managing Servers

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get <name>

# Remove a server
claude mcp remove <name>

# Check status in-session
/mcp

Configuration Scopes

# Add at user scope (available everywhere)
claude mcp add --transport http --scope user my-api https://api.example.com/mcp

# Add at project scope (shared with team)
claude mcp add --transport http --scope project my-api https://api.example.com/mcp

Transport Types

All three agents support two primary transports:

• Stdio — Local subprocess communication via stdin/stdout. Best for development servers and tools that need direct system access.
• Streamable HTTP — Remote connections over HTTP. The current standard for cloud-deployed servers. Works across the internet and through firewalls.

SSE (Server-Sent Events) is a legacy transport that is deprecated but still supported for backward compatibility.

The Hugging Face MCP Ecosystem

Hugging Face provides official MCP servers for Hub integration. Configure them in any MCP-compatible agent:

claude mcp add --transport http --scope user hf-mcp "https://huggingface.co/mcp?login"

The HF MCP server gives agents access to searching for models and datasets, reading repository files, querying model cards, and browsing Hub content.

Visit huggingface.co/settings/mcp to see official MCP servers and configuration examples for your agent.

Configuring Remote MCP Servers

For servers deployed to Hugging Face Spaces or other cloud platforms, use Streamable HTTP:

claude mcp add --transport http --scope user sentiment-analyzer https://username-sentiment.hf.space/mcp

claude mcp add --transport http --scope user code-reviewer https://username-reviewer.hf.space/mcp

Remote servers via Streamable HTTP don’t require restarting your agent, work across the internet and firewalls, can be updated independently, and support optional authentication via headers.

Debugging MCP Configurations

If a server isn’t working, check these things:

1. List configured servers:

claude mcp list
claude mcp get <server-name>

2. Test the server manually:

python /path/to/server.py

If the server crashes, you’ll see the error immediately.

3. Check environment variables:

echo $GITHUB_TOKEN

If empty, the server won’t have required secrets.

4. Check remote server URLs:

curl "https://your-space.hf.space/mcp"

Should return a valid response if the server is running.

Configuration Best Practices

Use environment variables for API keys and secrets, absolute paths for local server scripts, and one server per capability area (e.g. keep GitHub and Slack servers separate). Test servers locally first before deploying to the cloud. Use descriptive server names that indicate what each server provides, document your configuration, and keep configs in version control — without secrets.

Key Takeaways

Claude Code uses claude mcp add, Codex uses codex mcp add or config.toml, OpenCode uses opencode.json, and Pi commonly uses pi-mcp-adapter plus .mcp.json. The pattern is the same: name a server, pick a transport, and point it at a command (stdio) or URL (Streamable HTTP). Keep secrets in environment variables and test servers locally before debugging client config.

Next we’ll look at Gradio’s MCP integration in depth.