MCP Server

The CodeRadius MCP (Model Context Protocol) server transforms AI coding agents from local optimizers to architecture-aware collaborators. When connected, agents running inside your IDE can query your organization's full architectural graph in real time, at any point during their reasoning loop.

This page documents the MCP server, its tools, configuration options, and integration patterns.

What Is MCP?

The Model Context Protocol is an open standard for connecting AI models to external data sources and tools. An MCP server exposes a set of typed "tools" that an AI agent can call during a conversation, receiving structured JSON responses.

CodeRadius implements an MCP server that exposes your architectural graph as a set of query tools. When an agent in Cursor, Claude, or Windsurf encounters a task that benefits from architectural context — refactoring an API, renaming a database field, analyzing service dependencies — it can proactively call these tools without the engineer needing to manually provide context.

Starting the Server

cr mcp start

The server uses the stdio transport (standard input/output), which is the standard for local MCP integrations. The process remains alive as long as your IDE session is active.

IDE Configuration

{
  "mcpServers": {
    "coderadius": {
      "command": "cr",
      "args": ["mcp", "start"]
    }
  }
}

{
  "mcpServers": {
    "coderadius": {
      "command": "cr",
      "args": ["mcp", "start"]
    }
  }
}

{
  "mcpServers": {
    "coderadius": {
      "command": "cr",
      "args": ["mcp", "start"]
    }
  }
}

import { MCPClient } from '@mastra/mcp';

const coderadiusClient = new MCPClient({
  servers: {
    coderadius: {
      command: 'cr',
      args: ['mcp', 'start'],
    },
  },
});

const tools = await coderadiusClient.getTools();

Available Tools

evaluate_code_change_impact

Purpose: Calculates the architectural blast radius of a proposed code change before it is committed. This is the Impact Evaluation Engine exposed as an MCP tool. The agent provides proposed file contents; CodeRadius performs an in-memory topological diff and returns findings.

When agents use it: In agentic PR review workflows. An AI agent evaluating a PR can propose file modifications and verify their impact against the live graph before writing a PR comment — without touching the filesystem.

Input parameters:

Example usage in an agent:

const impact = await coderadiusMcp.callTool('evaluate_code_change_impact', {
  prTitle: "Rename userId to customerId in payment payload",
  changedFiles: [
    {
      path: "src/payments/dto/payment-created.dto.ts",
      proposedContent: "export interface PaymentCreatedDto { customerId: string; ... }"
    }
  ]
});

if (impact.findings.some(f => f.severity === 'DANGER')) {
  // Revise the proposed change to be backward-compatible
}

analyze_blast_radius

Purpose: Calculates the single-hop blast radius of a named resource (DataTable, MessageChannel, APIEndpoint). Returns all upstream producers that write to the resource and all downstream consumers that read from it.

When agents use it: Before proposing any change to a shared resource — renaming a database field, modifying an API endpoint's response schema, changing a message payload structure. The agent can check "if I change this, who breaks?" before writing a single line of code.

Input parameters:

Example response:

{
  "resource": {
    "type": "DataTable",
    "name": "orders",
    "urn": "cr:table:orders"
  },
  "producers": [
    { "service": "orders-service", "team": "commerce", "relationship": "WRITES" }
  ],
  "consumers": [
    { "service": "fulfillment-service", "team": "logistics", "relationship": "READS" },
    { "service": "reporting-service", "team": "data", "relationship": "READS" },
    { "service": "notifications-service", "team": "platform", "relationship": "READS" }
  ]
}

get_data_contract

Purpose: Returns the exact data schema of a known resource — the fields, their types, and whether they are required. Supports database tables, message payloads, and API specifications.

When agents use it: Before writing code that produces or consumes a known data structure. Prevents the agent from guessing field names or types, which is one of the most common sources of subtle cross-service breakage.

Input parameters:

Example response:

{
  "name": "order",
  "type": "message_payload",
  "fields": [
    { "name": "orderId", "type": "uuid", "required": true },
    { "name": "customerId", "type": "uuid", "required": true },
    { "name": "totalAmount", "type": "decimal", "required": true },
    { "name": "currency", "type": "string", "required": true },
    { "name": "status", "type": "enum(pending,paid,failed)", "required": true },
    { "name": "metadata", "type": "json", "required": false }
  ]
}

resolve_service_context

Purpose: Orients the agent within the architecture. Given a file path from the workspace, returns the matched service, its owning team, and the repository it belongs to.

When agents use it: At the start of any task involving a file modification, to establish "Where am I in the architecture? Who owns this? What team's conventions should I follow?"

Input parameters:

Example response:

{
  "service": "payments-service",
  "team": "platform-payments",
  "repository": {
    "name": "payments",
    "url": "https://gitlab.com/acme/payments"
  },
  "language": "TypeScript"
}

trace_data_lineage

Purpose: Follows a specific data field (e.g., customerId, email) across service boundaries — through message channels, APIs, and database tables — to build a multi-hop data lineage graph.

When agents use it: When a change to a specific field is proposed. The agent can verify which other services and data structures will be affected downstream, even through multiple hops.

Input parameters:

Example response:

{
  "field": "customerId",
  "lineage": [
    {
      "hop": 1,
      "from": "orders-service",
      "via": "APIEndpoint: POST /api/v1/orders",
      "to": "fulfillment-service",
      "survives": true
    },
    {
      "hop": 2,
      "from": "fulfillment-service",
      "via": "MessageChannel: fulfillment.completed",
      "to": "notifications-service",
      "survives": true
    }
  ]
}

list_services

Purpose: Returns all services known to the graph, with their team ownership, repository, programming language, and function count.

When agents use it: When working on a task that requires awareness of the full service catalog — for example, generating an impact summary of a proposed API change, or looking up which team to contact about an upstream dependency.

Input: No parameters required.

get_service_details

Purpose: Returns deep information about a specific service: its team owner, repository metadata, detected programming languages, exposed API interfaces (with endpoint counts), and the total number of functions indexed.

When agents use it: When the agent needs detailed context about a specific upstream or downstream dependency before proposing a change that affects it.

Input parameters:

analyze_architecture_gravity

Purpose: Performs a global analysis of the architectural graph to identify Single Points of Failure (SPOFs), shared database anti-patterns, and services with dangerously high coupling. Returns the top architectural "gravity wells" ranked by SPOF score (0–100).

When agents use it: In design review workflows, when an agent is evaluating the risk profile of a proposed architectural change. A high SPOF score on a target service indicates that any change carries disproportionate organizational risk.

Input: No parameters required.

analyze_agentic_context

Purpose: Returns the Agentic Context Radar data programmatically. Provides the full maturity matrix, capabilities catalog, context gaps, MCP census, and team overview aggregates for use within agentic workflows.

When agents use it: In organizational intelligence workflows — for example, an engineering leader's agent that runs weekly to summarize the state of AI adoption and surface new context gaps.

Input: No parameters required.

Security Considerations

The MCP server connects to your Memgraph instance using the credentials in ~/.coderadius/config/credentials.json or the environment variables configured via cr init. The server exposes read-only query tools only — it cannot modify the graph.

All communication between the MCP client (your IDE agent) and the MCP server (the cr mcp start process) is local (stdio). No data transits the network unless the Memgraph instance itself is remote.

Debugging MCP Issues

The agent doesn't seem to be calling CodeRadius tools:

1. Verify the MCP server configuration is registered in your IDE's MCP config file.
2. Restart the IDE after any configuration change.
3. Check that cr mcp start executes without errors when run manually in a terminal.

Tools return empty or unexpected results:

1. Verify that your MEMGRAPH_URI is pointing to the correct instance (production vs. development).
2. Run cr ui from the CLI to verify the graph is populated and accessible.

The server crashes on startup:

1. Run cr mcp start in verbose mode: CODERADIUS_DEBUG=1 cr mcp start
2. Ensure Memgraph is running: cr up