MCP servers

The Model Context Protocol (MCP) is an open standard for connecting agents to tools and data: issue trackers, databases, browsers, design tools, internal APIs. Cusp is an MCP client. Any server that works with another MCP client works with Cusp.

Configuration filesCopy Anchor Link

All files share one format:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    }
  }
}

When two scopes define a server with the same name, the higher scope's whole entry wins; fields are not merged. From highest to lowest: managed, command line, local, project, user, settings, then servers declared by subagents. Within a scope, .cusp/ files win over .mcp.json and ~/.claude.json.

TransportsCopy Anchor Link

stdioCopy Anchor Link

Cusp starts the server as a child process and talks to it over stdin and stdout.

HTTPCopy Anchor Link

Cusp connects to a remote server using the streamable HTTP transport, and falls back to the older SSE transport for servers that only support that.

Common fieldsCopy Anchor Link

VariablesCopy Anchor Link

${VAR} in any string is replaced with the environment variable VAR when the server starts. ${CUSP_PROJECT_DIR} and ${CLAUDE_PROJECT_DIR} are set to the project root. Keep secrets in your environment, not in committed files.

Expanded values, including any secrets, are never shown to the model.

Approving project serversCopy Anchor Link

A project's .mcp.json comes from whoever wrote the repository. Before Cusp connects to a server defined there, you approve it. The approval is tied to a hash of the exact entry, so if someone changes the command or URL later, Cusp asks again.

You can pre-approve in settings:

In an untrusted workspace, the project's own settings can't approve its servers.

Tools and resourcesCopy Anchor Link

Each server tool becomes a Cusp tool named mcp__<server>__<tool>. The input schema is the server's own JSON Schema.

MCP tools are deferred by default: the model sees their names and loads the definitions with ToolSearch when it needs one. This keeps a server with fifty tools from filling the context on every turn. Set alwaysLoad: true on a server whose tools the agent needs constantly.

Two built-in tools give access to server resources: ListMcpResourcesTool and ReadMcpResourceTool.

PermissionsCopy Anchor Link

MCP tools go through the permission engine like any other tool.

{
  "permissions": {
    "allow": ["mcp__github__get_issue", "mcp__github__list_pull_requests"],
    "ask": ["mcp__github__*"],
    "deny": ["mcp__postgres__execute"]
  }
}

Per-agent serversCopy Anchor Link

A subagent can list servers in its frontmatter, either by name or as an inline definition. Inline servers are available only to that agent. See Agents.

TroubleshootingCopy Anchor Link

• The server doesn't appear. Check that it's approved (project servers) and that the command runs on its own in a terminal.
• Tools are missing. They're deferred. Ask the agent to use the tool by name, or set alwaysLoad.
• Variables come through empty. ${VAR} reads from the daemon's environment. An app started from the Dock or Start menu may not see variables exported in your shell profile. Check with the CLI started from a terminal, which does.