Skip to content

MCP Servers

MCP (Model Context Protocol) servers give your agents access to external tools and data sources: databases, APIs, Kubernetes clusters, file systems, and more. Configure MCP servers at the team level and every agent in the team can use them.

How MCP Works in AgentCrew

MCP is an open standard for connecting AI models to external tools. AgentCrew supports three transport types:

Transport Description Example
stdio Local process communicating via stdin/stdout. The command runs inside the agent container. npx -y @modelcontextprotocol/server-postgres
http Remote HTTP server implementing the MCP protocol. https://mcp.sentry.dev/sse
sse Remote server using Server-Sent Events for streaming responses. https://api.example.com/mcp/sse

MCP configuration is global per team, not per agent. When you add an MCP server, it becomes available to the leader and all workers in the team.

Adding MCP Servers During Team Creation

In the team creation wizard (Step 2), scroll to the MCP Servers section at the bottom. For each server, provide:

  • Name: A unique identifier (e.g., postgres-db, kubernetes)
  • Transport: stdio, http, or sse

Then, depending on the transport:

stdio servers

  • Command: The binary to run (e.g., npx, uvx)
  • Args: Command arguments, comma-separated (e.g., -y, @modelcontextprotocol/server-postgres)
  • Environment Variables: Key-value pairs passed to the process (e.g., DATABASE_URL=postgresql://...)

http / sse servers

  • URL: The server endpoint (e.g., https://mcp.sentry.dev/sse)
  • Headers: Authentication or custom headers (e.g., Authorization: Bearer token)

Adding MCP Servers to Running Teams

You can add, edit, or remove MCP servers on teams that are already running:

  1. Open the team's chat view.
  2. Click the Settings icon to open the team settings modal.
  3. Select the MCP Servers tab in the sidebar.
  4. Use the form to add a new server or click Edit / Remove on existing ones.
Important: After adding or removing MCP servers, the agent process must be restarted to pick up the changes. The UI shows an amber warning banner with a Redeploy Team button when a redeploy is needed.

MCP Status Monitoring

Each MCP server shows its runtime status in the Settings modal. AgentCrew reports the actual runtime state of each MCP server by parsing status events from the AI provider (Claude Code init events and OpenCode runtime events). This gives you real-time visibility into whether each server started successfully or failed.

Status Indicator Meaning
Running Green dot The MCP server is running and available to agents. Confirmed by the AI provider runtime.
Failed Red dot The MCP server failed to start. Click the arrow to expand error details reported by the runtime.
Pending Gray dot The server is waiting for runtime status from the agent container. This is the initial state before the AI provider reports back.

When an MCP server has a Failed status, the error details are expandable directly in the server list. Common causes include:

  • Package not found (wrong npm/pip package name)
  • Remote server unreachable (wrong URL or network issue)
  • Command not found (binary not installed in the agent image)
  • Authentication failure (invalid credentials or expired tokens)
  • Timeout during dependency download

Provider Configuration

AgentCrew automatically generates the correct configuration file based on the team's AI provider:

Provider Config file Location
Claude Code .mcp.json /workspace/.mcp.json
OpenCode opencode.json /workspace/opencode.json

You do not need to write these files manually. The sidecar process generates them automatically from your MCP server configuration.

Examples

PostgreSQL Database

Name:      postgres-db
Transport: stdio
Command:   npx
Args:      -y, @modelcontextprotocol/server-postgres
Env:       DATABASE_URL = postgresql://user:pass@host:5432/mydb

Kubernetes Cluster

Name:      kubernetes
Transport: stdio
Command:   npx
Args:      mcp-server-kubernetes
Env:       KUBECONFIG_PATH = /path/to/kubeconfig

Sentry Error Tracking

Name:      sentry
Transport: http
URL:       https://mcp.sentry.dev/sse
Headers:   Authorization = Bearer <your-token>

Next Steps

  • Skills: Extend agent capabilities with installable skill packages.
  • Providers: Learn about supported AI providers and how MCP works with each.
  • Architecture: Understand how the sidecar generates MCP configuration files.