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 — configured per platform (Slack / Linear / GitHub) on Allowed Tools per Platform (/settings/tools)
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

​
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:

​
Self-hosted runtime

Set the variable on the machine where cyrus is running:

​
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:
For the Stripe server:
  • Allow all Stripe tools
  • Allow a single tool only
If you’re unsure which tools you’ll need, start by allowing the server.

​
Where to configure allowed tools

Tool gating lives on Allowed Tools per Platform (/settings/tools in the Cyrus webapp). It is configured per platform (Slack / Linear / GitHub) — Cyrus is reachable from each of those surfaces independently, and each has its own allow-list:
  • Slack — Cyrus replying to @mentions
  • Linear — Cyrus working a Linear issue
  • GitHub — Cyrus reacting to a PR comment or webhook
Open the tab for the surface you care about, find the MCP Servers section, and toggle the server’s tools on. You can:
  • Toggle the whole server on (mcp__stripe) to allow every tool it exposes
  • Toggle individual tools on (mcp__stripe__retrieve_charge) for narrower access

​
Per-repository overrides

If you want a specific repository to deviate from the team-level platform list, open that repo’s row on /settings/tools and use Allowed Tools to set a custom list. The override applies to both Linear and GitHub sessions on that repo (Slack is repo-agnostic and has no per-repo override). The MCP Servers section is available inside the dialog too, so per-repo MCP gating works the same way. If a tool is not enabled on the relevant tab (or, when a repo override is active, in that override), 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}
cyrus-f1

Cyrus Community

Get support and ask questions on Discord