Model Context Protocol

Give your AI agents
structural awareness of your codebase

BlueLens MCP exposes your CodeGraph — nodes, dependencies, blast-radius analysis, and architectural rules — directly to Claude, Cursor, and any MCP-compatible agent.

Get startedBrowse tools

Architecture

Two ways to connect

BlueLens MCP runs either locally alongside your editor (zero setup, your data never leaves your machine) or as a hosted cloud endpoint your agents can reach from anywhere.

💻
Local · stdio

Local MCP (npm)

The @bluelens/mcp package runs as a stdio process on your machine. It reads your local CodeGraph directly from disk. No account required. Works with any MCP client.

☁️
Cloud · HTTP

Cloud MCP (this server)

A hosted Streamable HTTP endpoint at mcp.bluelens.dev/api/mcp. Push your CodeGraph once with push_to_cloud, then any agent anywhere can query it with just a Bearer token.

Local MCP
@bluelens/mcp
→
push_to_cloud
→
Cloud Storage
per-user namespace
→
AI Agent
Claude / Cursor / …

Installation

Get up and running

Option A — Local (npm)

No account needed. Runs on your machine, reads your local CodeGraph.

1

Install the package globally

shell
npm install -g @bluelens/mcp
2

Add to your MCP client config

Point your client at the bluelens-mcp binary. See Configure for client-specific examples.

3

Open BlueLens, generate a CodeGraph

In the BlueLens editor (app.bluelens.dev), open your project and run a CodeGraph scan. The graph is stored locally; the MCP server reads it on demand.

Option B — Cloud (Hosted HTTP)New

Your agents connect via HTTP from anywhere — no local process needed on the agent side.

1

Install the local MCP (needed for the push step)

shell
npm install -g @bluelens/mcp
2

Choose an API key

Any secret string works as your API key — it namespaces your data on the server. Generate one with:

shell
openssl rand -hex 32
3

Push your CodeGraph to the cloud

In any MCP-enabled session with your local server, call:

tool call
push_to_cloud(
  graph_id: "<your-graph-id>",
  cloud_url: "https://mcp.bluelens.dev",
  api_key:   "<your-secret-key>"
)
4

Point your agents at the cloud endpoint

Configure the cloud server as an HTTP MCP server. See Configure below.

Configuration

Connect your AI client

Claude Code

Local (stdio)
~/.claude/claude_desktop_config.jsonjson
{
  "mcpServers": {
    "bluelens": {
      "command": "bluelens-mcp",
      "args": []
    }
  }
}
Cloud (HTTP)
~/.claude/claude_desktop_config.jsonjson
{
  "mcpServers": {
    "bluelens-cloud": {
      "type": "http",
      "url":  "https://mcp.bluelens.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Cursor

Local (stdio)
~/.cursor/mcp.jsonjson
{
  "mcpServers": {
    "bluelens": {
      "command": "bluelens-mcp",
      "args": []
    }
  }
}
Cloud (HTTP)
~/.cursor/mcp.jsonjson
{
  "mcpServers": {
    "bluelens-cloud": {
      "url": "https://mcp.bluelens.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Direct HTTP (any client)

shell
# Test connectivity
curl https://mcp.bluelens.dev/api/mcp \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
💡

API key security: your key is hashed with SHA-256 before being used as a storage namespace. The raw key is never stored. Any secret string of 16+ characters works.

Reference

Available tools

All tools are available in both the local and cloud server unless otherwise noted.

Analysis

find_nodesSearch for graph nodes by name, file path, kind (module, class, function…), or depth. Returns node IDs for use in other tools.
analyze_node_impactBlast-radius analysis for a node: direct dependents, direct dependencies, and transitive impact depth. Returns a risk score.
find_dependency_pathShortest dependency path between two nodes. Reveals hidden coupling across domain boundaries.
diff_codegraphsStructural diff between two CodeGraph snapshots: added/removed modules, dependency changes, domain drift.
check_architectural_rulesEnforce custom rules: forbidden cross-domain imports, fan-in thresholds. Optionally report only new violations against a base graph.

CodeGraph

list_codegraphsList all stored CodeGraphs, optionally filtered by workspace.
get_codegraph_summaryHigh-level summary: node counts by kind, top-level domains, relationship stats.
get_codegraph_nodesPaginated node listing with filters for depth, kind, and parent. Core navigation primitive.
detect_codegraph_anomaliesFinds structural issues: circular dependencies, orphaned nodes, broken references, high coupling.
delete_codegraphRemove a stored CodeGraph by ID.

Workspaces & Diagrams

list_workspacesList all workspaces in this account.
create_workspaceCreate a new named workspace.
delete_workspaceDelete a workspace and all its contents.
list_foldersList folders within a workspace.
list_diagramsList all diagrams, optionally filtered by workspace or folder.
get_diagramRetrieve a diagram's full content by ID.
search_diagramsFull-text search across diagram titles and content.

Local-only tools

push_to_cloudlocal MCP only
Upload a CodeGraph from your local machine to the cloud server. Requires graph_id, cloud_url, and api_key.

Usage

Example agent prompts

Once connected, your agent can reason about your codebase's structure without reading every file.

“What is the blast radius of changing utils/auth.ts?”

Agent calls find_nodes to locate the module, then analyze_node_impact for transitive dependents.

“Do any modules in the 'api' domain import from 'ui'?”

Agent calls check_architectural_rules with a forbidden_cross_domain rule.

“What changed structurally between last week's graph and today's?”

Agent calls diff_codegraphs on two snapshots to surface added/removed modules and new dependencies.

“How is PaymentService coupled to the rest of the system?”

Agent calls find_nodes, then analyze_node_impact to show fan-in, fan-out, and risk score.

“Find the shortest path between UserController and DatabasePool.”

Agent calls find_dependency_path — reveals indirect coupling chains.

REST API

Graph upload endpoint

In addition to the MCP protocol endpoint, the cloud server exposes a REST endpoint for pushing CodeGraphs programmatically.

httpPOST /api/graphs
# Headers
Authorization: Bearer <your-api-key>
Content-Type: application/json

# Body — CodeGraph JSON (exported from BlueLens editor)
{
  "id": "graph_abc123",
  "name": "my-service",
  "nodes": { ... },
  "relations": { ... }
}

# Response
{
  "success": true,
  "graphId": "graph_abc123",
  "nodeCount": 412
}
🔑

Workspace auto-creation: if the graph's workspaceId doesn't exist in your account, a “Default” workspace is created automatically. No pre-setup needed.