Agent

DocsAgentMCP Servers

Connect external MCP (Model Context Protocol) servers to the Spectral agent — GitHub, Jira, Slack, filesystem, and more. Simple JSON config, local and remote servers, and import from other editors.

MCP Servers

The Spectral agent speaks MCP (Model Context Protocol) as a client. Connect any MCP server — a GitHub server to list PRs, Jira to manage issues, Slack for messaging, or a custom tool you built — and the server's tools become callable by the agent alongside its built-in tools.

Note: This is about connecting external MCP servers to the Spectral agent. For the inverse — exposing Aexol cloud tools to your editor — see Remote MCP.

MCP Servers

You can connect both local (stdio-based, running on your machine) and remote (HTTP/SSE, hosted on a server) MCP servers. Local servers launch as child processes; remote servers connect over the network. Both appear identically to the agent once connected.

Config File Locations

The agent discovers MCP servers from four JSON files, merged in this order (later files override earlier ones by server name):

#ScopeShared vs. Spectral-onlyPath
1GlobalShared (any MCP client)~/.config/mcp/mcp.json
2GlobalSpectral agent only~/.spectral/agent/mcp.json
3ProjectShared (any MCP client)./.mcp.json
4ProjectSpectral agent only./.spectral/mcp.json
  • Global servers load in every session. Project servers load only when the agent runs inside that project.
  • Shared files use the standard format that Cursor, Claude Code, and others also read. Spectral-only files keep servers private to the agent.

Connecting a Server

Create .spectral/mcp.json in your project root:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://my-mcp-server.example.com",
      "headers": {
        "Authorization": "Bearer $ENV_VAR"
      }
    }
  }
}

For stdio servers, use "command" and "args" instead of "url". The agent auto-detects the transport from the server definition.

Importing from Other Tools

Instead of duplicating config, point the agent at MCP configs you already have for other tools. Add an imports array to any config file:

{
  "imports": ["cursor", "claude-code"],
  "mcpServers": {}
}

Supported imports: Cursor, Claude Code, Claude Desktop, Codex, Windsurf, and VS Code. Imported servers merge with your explicit entries; explicit entries always win on name conflicts.

Verifying Setup

Start the agent and use these slash commands to verify:

CommandWhat it does
/mcp or /mcp statusShow setup status: discovered files, imports, connection state
/mcp toolsList every MCP tool currently available to the agent
/mcp reconnect <name>Reconnect a specific server (e.g. after rotating a token)
/mcp setupShow onboarding: adopt imports or scaffold a starter config
/mcp-auth <name>Run OAuth for a server that requires authentication

The status bar shows MCP: N/N servers so you can tell at a glance whether all configured servers connected.

Troubleshooting

ProblemLikely causeFix
Server shows failedBad command path or missing envCheck command/args, ensure tokens are set in env
needs auth statusOAuth required, not yet runRun /mcp-auth <server-name>
Tools missingFiltered out or import path wrongCheck excludeTools/directTools; verify imports path
401 on HTTP serverWrong header or tokenConfirm Authorization value; use a valid token
Server not discoveredWrong file locationUse one of the four canonical paths; check /mcp status

Set "debug": true on a server entry to surface its stderr in the agent log when diagnosing connection issues.

See also