Skip to main content
Cyrus supports custom MCP (Model Context Protocol) servers, which allow it to interact with external systems during tasks like debugging, validation, and analysis. You can add any MCP server (external providers, internal services, third-party APIs) as long as:
  • It’s defined in your repository
  • Secrets are provided via environment variables
  • The tools are explicitly allowed
This guide walks through setup using Stripe as a concrete example.
Support for OAUTH driven authentication for ‘remote’ MCP servers is not yet supported for Cloud-hosted runtimes

​
What You’re Setting Up (Mental Model)

  1. .mcp.json defines which MCP servers exist and what they need
  2. Environment variables provide secrets (API keys, tokens)
  3. Allowed Tools define what Cyrus is permitted to call
Environment variables for MCP servers depend on how you run Cyrus:
  • Hosted / Team plans:
    Environment variables are configured in the Cyrus web app and injected automatically.
  • Self-hosted or Semi-hosted:
    Environment variables must be set on your own machines or infrastructure where Cyrus runs.
If Cyrus cannot access the environment variables at runtime, MCP servers will not start.

​
Step 1 — Define the Stripe MCP Server (.mcp.json)

Start by adding a .mcp.json file to the root of your repository and ensure it gets merged to the branch considered by Cyrus to be the default branch. This file declares:
  • The MCP server name
  • How to start it
  • Which environment variables it expects

​
Example: Stripe MCP Server

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["@stripe/mcp-server"],
      "env": {
        "STRIPE_API_KEY": "${STRIPE_API_KEY}"
      }
    }
  }
}

​
What’s happening here

  • stripe is the server name
  • No secrets are committed
  • ${STRIPE_API_KEY} is a placeholder, which will be automatically replaced with the value associated with the STRIPE_API_KEY environment variable in your shell
Reference: https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json

​
Step 2 — Provide Environment Variables

How you provide variables depends on your deployment mode.

​
Cloud-Hosted Runtime

In the Cyrus web app:
  1. Go to Repos
  2. Click the vertical ellipsis menu (⋯)
  3. Select ‘Environment variables’
  4. Add the following environment variable to a ‘.env’ file at the repository root:
STRIPE_API_KEY = sk_live_...

​
Self-Hosted Runtime

Set the variable on the machine where cyrus is running: 
export STRIPE_API_KEY=sk_live_...

​
Step 3 — Allow Stripe MCP Tools

Even with the server defined and secrets configured, Cyrus will not call MCP tools unless they’re explicitly allowed. This is a safety boundary.

​
How MCP Tool Names Work

Cyrus namespaces MCP tools using this format: 
mcp__<server>
mcp__<server>__<tool>
For the Stripe server:
  • Allow all Stripe tools 
    mcp__stripe
  • Allow a single tool only 
    mcp__stripe__retrieve_charge
If you’re unsure which tools you’ll need, start by allowing the server.

​
Where to Configure Allowed Tools

In the same Repos page:
  • Find Allowed Tools (click elipses of project)
  • Add the appropriate mcp__stripe entry
If a tool is not listed here, Cyrus will refuse to call it, even if instructed.

​
Setup Complete

At this point:
  • Stripe MCP server is defined
  • Stripe API key is configured
  • Tool permissions are granted
Cyrus is now capable of interacting with Stripe.

​
Using MCP From a Linear Issue

Create a Linear issue and include guidance in the title or description.

​
Example Instructions

  • “Use Stripe to check whether this customer was charged twice”
  • “Query recent Stripe payment failures and summarize the issue”
  • “Validate whether the refund was successfully processed in Stripe”
Cyrus will:
  • Detect the instruction
  • Call the Stripe MCP tools (if allowed)
  • Use the results during reasoning or debugging

​
Common Pitfalls

​
MCP tools aren’t being called

Check:
  • .mcp.json exists at the repo root
  • Any environment variable the MCP server needs (server specific) is available at runtime
  • mcp__<servername_name> (allow all) or mcp__<servername>__<toolname> is listed in Allowed Tools

​
Secrets were committed

Rotate the key immediately, then:
  • Remove it from git
  • Move it into environment variables
  • Reference it using ${YOUR_ENV_VAR}
fOjhOFI

Cyrus Community

Get support and ask questions on Discord