MCP Servers

Model Context Protocol (MCP) servers give the agent tools it does not have built in: your issue tracker, a database, a browser, an internal API. You list servers in mcp.json, and their tools become available to the agent alongside its own.

The CLI, the VS Code extension and the Desktop app (Code Mode) read the same files, so a server you add in one shows up in the others.

Add your first server

Start a CLI session and add a server. This one gives the agent a browser through Playwright:
```
/mcp add playwright npx -y @playwright/mcp@latest
```
Type /mcp to open the manager. The server should show connected with its tool count.
Ask for something that needs it: "Open example.com and tell me the page title."

/mcp add writes the server to ~/.abacusai/mcp.json, so it is available in every project. In VS Code, open Abacus Settings, scroll to MCP servers and choose Add server.

Common setups

A local server

A local (stdio) server is a program the agent starts on your machine.

~/.abacusai/mcp.json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

The server inherits your environment, and anything in env is added on top.

A remote server with an API token

~/.abacusai/mcp.json
{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

${GITHUB_TOKEN} is read from your environment, so the token is not written into the file. See Environment variables.

A remote server that signs in with OAuth

Many hosted servers, such as Notion, Sentry and Linear, use OAuth. Add the URL and nothing else:

/mcp add notion https://mcp.notion.com/mcp

The server shows needs authentication in /mcp. Select it, choose Authenticate, and sign in in the browser. See Signing in with OAuth.

Paste a config from a server's README

Most servers publish a JSON snippet for Claude Desktop or Cursor. That shape works here unchanged: paste the entry under mcpServers in mcp.json, or pass it to /mcp add-json:

/mcp add-json github '{"url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer ${GITHUB_TOKEN}"}}'

Where servers are configured

Scope	File	Who gets it
User	`~/.abacusai/mcp.json`	You, in every project. `/mcp add` and Add server in VS Code write here.
Project	`<project>/.abacusai/mcp.json`	Everyone who opens the project, once they trust the folder. Commit it.
One run	`abacusai --mcp-config <file>`	That run only. Repeat the flag for more files.
Extra files	`additionalMcpConfigPaths` in `config.json`	Every session. A list of file paths.

The project file is read from the folder the CLI was started in, or the first VS Code workspace folder, so start the CLI at the repository root.

When two files define a server with the same name, --mcp-config and additionalMcpConfigPaths files win, then your user file, then the project file. The winning entry is used as it is; fields are not merged.

To switch off a server a project ships without editing its file, add an entry with the same name and only "disabled": true to your user file:

~/.abacusai/mcp.json
{
  "mcpServers": {
    "shared-db": { "disabled": true }
  }
}

Reuse servers from other tools

Turn on External MCP configs (loadExternalMcpConfigs) to also read servers you set up in other tools. Restart to apply.

Tool	Files read
Cursor	`~/.cursor/mcp.json`, `<project>/.cursor/mcp.json`
VS Code	`<project>/.vscode/mcp.json`
Claude Desktop	`claude_desktop_config.json` in `~/Library/Application Support/Claude/` (macOS), `%APPDATA%\Claude\` (Windows) or `~/.config/Claude/` (Linux)
Windsurf	`~/.codeium/windsurf/mcp_config.json`

These files are never edited here. Removing one of their servers adds a "disabled": true entry to the matching .abacusai/mcp.json instead. Claude Code's config is not read this way; use /import.

Manage servers

In the CLI

Command	What it does
`/mcp`	Opens the manager: every server with its status, tools and errors
`/mcp add <name> <command-or-url> [args...]`	Adds a server to `~/.abacusai/mcp.json`. An `http://` or `https://` address becomes a remote server; anything else is the command to run.
`/mcp add-json <name> '<json>'`	Adds a server from a JSON definition

In the manager, select a server to see its tools and recent log lines, then choose Authenticate, Reconnect, Sign out or Remove server. Remove server deletes the server from every file that defines it.

The manager also lists your Abacus.AI connectors, such as Gmail and Slack, which you connect through the Abacus.AI web app.

Status	Meaning
connected · N tools	Working
connecting	Starting up
needs authentication	Waiting for you to sign in
failed	Could not start or connect. Select it to see why.
stopped	Not running
invalid config	The entry or the file has an error. The reason is shown.
not loaded · untrusted folder	A project server waiting for you to trust the folder
disabled	`"disabled": true`
env var not set	The entry uses a `${VAR}` that is not set. See Environment variables.

In VS Code

Open Abacus Settings and scroll to MCP servers. The list shows the servers from your user and workspace mcp.json, each with its status. Add server writes to your user file, the edit icon updates the file a server came from, and the delete icon removes the server everywhere, as in the CLI. A server that needs sign-in shows auth required with an address to open in your browser. Sign-ins are shared by the CLI, the extension and the Desktop app.

When changes take effect

Changes made through /mcp, /import or the VS Code settings apply straight away. After editing mcp.json by hand, restart the CLI or reload the VS Code window. When a running server's tool list changes, the new tools appear without a restart.

Signing in with OAuth

A remote server with no headers, or with an oauth block, signs in with OAuth when it asks for it:

The server shows needs authentication.
Choose Authenticate in /mcp, or open the sign-in address from VS Code, and sign in in the browser.
The browser returns to http://127.0.0.1:33418/oauth/callback, and the server connects. Tokens are refreshed for you from then on.

If you do not finish within five minutes, start again from /mcp.

The agent registers itself with the server automatically. For a server that does not support that, register an app with the provider and add its details:

{
  "mcpServers": {
    "internal-api": {
      "url": "https://mcp.internal.example.com/mcp",
      "oauth": {
        "clientId": "abacus-agent",
        "clientSecret": "<only if your provider issued one>",
        "scope": "read write offline_access"
      }
    }
  }
}

Register http://127.0.0.1:33418/oauth/callback as the redirect address. If that port is taken, set mcpOAuthPort in your user config.json and register that port instead. Some providers issue a refresh token only when offline_access is in the scope.

A server with headers and no oauth block never starts a sign-in, so an API key in headers is enough. "oauth": false turns sign-in off for any server.

Using MCP tools

The agent sees each server's tools and calls them when they fit the task. You can also name the server: "use the github tools to list my open PRs".

Permissions

A tool the server marks as read-only runs without asking, unless a deny or ask rule covers it. A tool the server marks as requiring confirmation asks on every call, in every mode. Everything else follows your permission mode and rules, which name MCP tools as mcp__<server>__<tool>:

.abacusai/config.json
{
  "permissions": {
    "allow": ["mcp__github__list_issues", "mcp__playwright__*"],
    "deny": ["mcp__github__delete_repository"],
    "ask": ["mcp__shared-db"]
  }
}

mcp__<server> covers every tool from that server. A deny rule with no arguments, such as mcp__shared-db, also hides the tools from the agent.

Approval lists inside mcp.json, such as Cline's autoApprove, are ignored. Use permissions.allow rules instead.

Limits

On Abacus.AI models, the agent gets the first 50 MCP tools across all your servers, and a notice says when some were left out. On a local provider every tool is passed on.
A tool call stops after the toolTimeoutMs setting, 120 seconds by default and up to 600 seconds. A call that goes 60 seconds without a result or a progress update also stops.
Stdio, Streamable HTTP and SSE servers are supported. MCP prompts and resources are not used.

In print mode and CI

abacusai -p loads the same servers as an interactive session. A project's .abacusai/mcp.json loads only in a trusted folder or with ABACUS_TRUST_WORKSPACE=1, while --mcp-config files always load:

GITHUB_TOKEN=... abacusai -p "Summarise the open issues labelled bug" \
  --mcp-config ./ci/mcp.json

Print mode cannot open a browser to sign in. Sign in once interactively on that machine, or use a server that takes a token in headers from an environment variable. See Scripting and CI.

Importing from Claude Code

/import in the CLI copies your Claude Code MCP servers, along with your skills and settings. Run /import --dry-run first to see the list.

Claude Code source	Written to
`<project>/.mcp.json`, and this project's entries in `~/.claude.json`	`<project>/.abacusai/mcp.json`
User entries in `~/.claude.json`	`~/.abacusai/mcp.json`

A server whose name is already configured is skipped, never overwritten.

Differences from Claude Code, Codex and OpenCode

Topic	Claude Code	Codex	OpenCode	Here
Config files	`.mcp.json` and `~/.claude.json`	`[mcp_servers.<name>]` in `~/.codex/config.toml` or a trusted project's `.codex/config.toml`	`mcp` in `opencode.json`	`mcpServers` in `.abacusai/mcp.json` and `~/.abacusai/mcp.json`
Environment variables	`${VAR}`, `${VAR:-default}`	`env_vars`, `bearer_token_env_var`	`{env:VAR}`	`${VAR}`, `${VAR:-default}`
Tool call time limit	`MCP_TOOL_TIMEOUT`, or `timeout` per server	`tool_timeout_sec` per server	`timeout` per server	`toolTimeoutMs` for every tool. A per-server `timeout` is ignored.

Claude Code's mcpServers entries can be pasted as they are. Codex's TOML is not read; copy each server into mcp.json by hand.

Sources: Claude Code's MCP, Codex's MCP and OpenCode's MCP servers.

Configuration reference

mcp.json holds one object, mcpServers, keyed by server name. The file may contain // comments and trailing commas.

Field	Applies to	What it does
`command`	stdio	The program to run. Required for stdio.
`args`	stdio	Its arguments
`env`	stdio	Environment variables added to the ones the server inherits
`url`	remote	The server address. Required for remote servers.
`headers`	remote	HTTP headers sent with every request, such as `Authorization`
`oauth`	remote	`clientId`, `clientSecret` and `scope` for a pre-registered OAuth app, or `false` to turn sign-in off
`type`	all	`"stdio"`, `"http"` or `"sse"`. Usually left out: an entry with `url` is remote, and a `url` ending in `/sse` uses SSE.
`disabled`	all	`true` keeps the server off

Other fields, such as cwd and timeout, are ignored. Servers go in mcp.json files only; an mcpServers key in config.json is not read.

Environment variables

${NAME} or ${NAME:-default} in command, args, env, url or headers is replaced with that environment variable from the environment you started the CLI, VS Code or the Desktop app in.

default is used only when the variable is unset. A variable set to an empty string expands to nothing.
An unset variable with no default is passed to the server as the literal text ${NAME}, and /mcp and the VS Code list flag the server with the variable's name.
In url, an unset variable with no default stops the server connecting, with an error naming the variable.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    }
  }
}

Security and trust

An MCP server runs with your permissions. A local server can read your files and reach your network, and a remote server receives whatever the agent sends it. Add servers you would run yourself, and remember that a server that fetches outside content, such as web pages, tickets or email, can feed the agent instructions you did not write.

A server in <project>/.abacusai/mcp.json is a program the repository asks your machine to run, so it does not start until you trust the folder. The trust prompt lists each server with the command it runs or the address it reaches. In VS Code, VS Code's Workspace Trust decides.

Values in env and headers are stored as written, so use ${VAR} references and keep real tokens out of any mcp.json you commit. OAuth tokens are stored in ~/.abacusai/mcp-auth/, readable only by your user account. Sign out in /mcp deletes them.

To share servers with a team, commit <project>/.abacusai/mcp.json with a ${VAR} reference for every secret. Each person sets the variables or signs in on their own machine. To block a server's tools for the whole team, commit a deny rule such as "deny": ["mcp__shared-db"] in the project's .abacusai/config.json. Deny rules apply even before a folder is trusted.

Troubleshooting

Open /mcp first. A failed server shows the reason, and selecting it shows its log. /doctor config also reports an mcp.json that does not parse.

The server does not appear

The file does not parse. /mcp and the VS Code settings page show the line and column.
It is in a project file and the folder is not trusted.
You edited the file by hand during a session. Restart.
A file with higher priority defines the same name, possibly as "disabled": true.
The CLI was started in a subfolder, so the project's .abacusai/mcp.json was not found.

A local server fails to start

The command is not on your PATH. Run it yourself in a terminal first, or give an absolute path in command.
A variable it needs is not set, and /mcp shows env var not set. Set it in the environment you start the CLI or VS Code from, or give it a default with ${VAR:-default}.
The server prints logs to stdout. A stdio server must keep stdout for protocol messages.

Sign-in did not finish within five minutes, or the browser could not reach 127.0.0.1:33418. Try Authenticate again, and change the port with mcpOAuthPort if something else uses it.
The server does not support automatic registration. Add an oauth block with a client you registered, or use a token in headers.
The provider issues no refresh token. Add offline_access to scope.
To start over, choose Sign out for the server, then Authenticate.

Tools are missing or the agent ignores a server

On Abacus.AI models you have more than 50 MCP tools and the ones you want were left out. Disable servers you do not need.
The tool descriptions are vague. Name the server in your request.

A tool call times out

Raise Tool timeout (toolTimeoutMs) in /settings, up to 600 seconds. A tool that runs longer than a minute must also send progress updates. For work longer than ten minutes, split it into a tool that starts a job and another that checks on it.

For further help, reach out at support@abacus.ai.

Add your first server​

Common setups​

A local server​

A remote server with an API token​

A remote server that signs in with OAuth​

Paste a config from a server's README​

Where servers are configured​

Reuse servers from other tools​

Manage servers​

In the CLI​

In VS Code​

When changes take effect​

Signing in with OAuth​

Using MCP tools​

Permissions​

Limits​

In print mode and CI​

Importing from Claude Code​

Differences from Claude Code, Codex and OpenCode​

Configuration reference​

Environment variables​

Security and trust​

Troubleshooting​

The server does not appear​

A local server fails to start​

A remote server keeps asking to sign in​

Tools are missing or the agent ignores a server​

A tool call times out​