Skip to content

MCP servers

MCP servers let you give the agent access to external tools and data — an issue tracker, a database, a documentation service, an internal API. Once connected, their capabilities appear to the agent as extra tools it can use during a task.

MCP (the Model Context Protocol) is an open standard, so many ready-made servers exist and you can point gdc at any of them.

How connected tools appear

When you add a server named git, its tools show up in the agent's toolset with a git prefix (for example mcp_git_status). This keeps them clearly grouped and separate from gdc's built-in tools.

Like any tool that can act, MCP tools are governed by permissions. By default the agent asks before using them; you can mark a server trusted to allow its tools without prompting.

Two kinds of server

gdc supports two ways of connecting, and picks automatically based on what you configure:

  • Local program — gdc launches a command and talks to it over its input/output. Best for tools that run on your machine.
  • Remote service — gdc connects to a URL over HTTP. Best for hosted services.

Adding a server

The easiest way is the command line, which edits your configuration for you (preserving your comments and formatting):

gdc mcp add git uvx --arg mcp-server-git --arg --repo --arg . --trusted

This registers a server named git that runs uvx mcp-server-git --repo ..

gdc mcp add-http docs https://example.com/mcp \
  --auth-header "Bearer YOUR_TOKEN"

You can also edit configuration directly:

~/.gdc/config.toml
[mcp.servers.git]                 # local program
command = "uvx"
args    = ["mcp-server-git", "--repo", "."]
trusted = true

[mcp.servers.docs]                # remote service
url         = "https://example.com/mcp"
auth_header = "Bearer YOUR_TOKEN"
trusted     = false               # the agent will ask before using it

→ Configuration reference

Managing servers

gdc mcp list                 # every configured server
gdc mcp list --json          # machine-readable
gdc mcp trust git            # mark trusted (use --no to untrust)
gdc mcp remove git           # remove a server

By default these edits apply to the project you're in. Add --scope user to change your user-wide configuration instead.

Scope: project vs. user

  • Project scope (default for add/remove) keeps a server tied to one repository — good for project-specific tools you want your teammates to share.
  • User scope makes a server available in every project — good for general tools like a web search or a personal notes service.

Trusted or not

A server that isn't trusted means the agent must get your approval each time it uses one of that server's tools. Trust a server only when you're comfortable letting the agent use it freely. You can review what's been granted at runtime and revoke it:

gdc permissions list --server git