Skip to content
Documentation

MCP servers in the AI agent

MCP (Model Context Protocol) servers give the agent extra tools. The agent supports two kinds:

KindWhere it runsWhere it is configured
HostedOutside your machine; CHAMPREP connects to it over HTTPSYour CHAMPREP AI account, shared with the web, desktop, and mobile apps
LocalA program started on your machine, speaking MCP over standard input and outputAn mcp.json file for you or for the project

This page is about connecting servers to the agent. To use CHAMPREP itself from another MCP client, see the CHAMPREP MCP server.

/mcp

The window lists every hosted and local server with its status and tools. Select a server with the arrow keys and press:

KeyAction
EnterShow the actions for the server.
eTurn the server on or off.
rRefresh: reconnect and reload its tools.
aRe-authenticate: replace its credential.
tList its tools.
xRemove the server.
nAdd a server.

Shortcuts also work without the window, for example /mcp list, /mcp enable NAME, /mcp disable NAME, /mcp refresh NAME, and, for local servers, /mcp restart NAME and /mcp remove NAME.

Hosted servers belong to your CHAMPREP AI account, so a server you add in the terminal is also available on the web, and the other way round. Their tools run on CHAMPREP, not on your machine.

To add one, press n in /mcp, choose a hosted server, and enter its URL and credential, such as a bearer token. The credential is entered in a masked field, sent once to your CHAMPREP AI account, and never shown, saved locally, logged, or given to the model. Use a to replace an expired credential.

Removing a hosted server removes it from your account on every surface. If a hosted-server action is not available from the CLI in your environment, the agent says so; use your CHAMPREP AI settings on the web instead.

Local servers are programs the agent starts on your machine. Add one with n in /mcp and choose:

  • the server name and the command with its arguments;
  • for just you (your user mcp.json) or for this project (.champrep/mcp.json, which you can commit);
  • optionally, an environment variable that holds a credential. Its value is masked, stored only in your user mcp.json, and never written to a project file, history, logs, or the model’s context.

You can also edit the files directly. They use the common MCP client format. Keep credentials in your user file, never in a project file you commit:

{
"mcpServers": {
"github": {
"command": "github-mcp-server",
"args": ["stdio"],
"env": { "GITHUB_TOKEN": "YOUR_TOKEN" }
}
}
}

Optional fields per server: disabled, include_tools, exclude_tools, startup_timeout_sec (default 30), tool_timeout_sec (default 120, maximum 600), and priority. Only local (stdio) servers belong in these files; add HTTP servers as hosted servers.

Local servers never receive your CHAMPREP credentials or any CHAMPREP_* environment variable.

Run champrep ai paths to find your user mcp.json. Local MCP servers are a plan feature; see Plans and limits.

A project’s .champrep/mcp.json runs commands on your machine, so its servers start only after you trust the project’s .champrep/ configuration. If the file changes, you are asked again. See Repository trust.

  • Local server tools are treated like commands: each call asks for your permission, showing the server and arguments, unless an allow rule covers it. For example, local_mcp__github__* allows every tool of the github server. Deny rules work the same way.
  • Hosted server tools follow the approval setting of the server in your CHAMPREP AI account. When a call needs approval, the agent shows an approval card; nothing is approved automatically.

The agent can offer at most 64 local tools per turn. When local servers provide more, lower-priority servers are trimmed first and the agent tells you. Use include_tools or exclude_tools to keep the tools you need.