---
title: MCP & Claude Desktop Integration
description: MCP tools for orchestration, experts, workflows, consensus, research, memory, and tracing
tier: 2
keywords: [mcp, tool, server, claude-desktop, stdio, integration]
related_files: [docs/ENTRYPOINTS.md, docs/reference/capabilities.md]
---

# MCP & Claude Desktop Integration

Configure nexus-agents as an MCP server for Claude Desktop with full tool access.

Nexus-agents implements the Model Context Protocol (MCP) 2025-11-25 specification, enabling seamless integration with Claude Desktop and other MCP-compatible clients.

## Quick Setup

### 1. Install nexus-agents

```bash
npm install -g nexus-agents
```

### 2. Configure Claude Desktop

Add nexus-agents to your Claude Desktop MCP configuration:

**Project-scoped (recommended):** `.mcp.json` in project root
**Global:** `~/.claude.json` (MCP config stored under `projects` key)

```json
{
  "mcpServers": {
    "nexus-agents": {
      "command": "nexus-agents",
      "args": ["--mode=server"]
    }
  }
}
```

### 3. Restart Claude Desktop

After updating the configuration, restart Claude Desktop to load the MCP server.

### 4. Verify Integration

In Claude Desktop, ask:

> "orchestrate: What are the main components of this codebase?"

Claude will use the nexus-agents orchestration tool to analyze and respond.

## MCP Tools Reference

Nexus-agents provides a comprehensive set of MCP tools that Claude can use. The most commonly used tools are documented below. See [ENTRYPOINTS.md](../ENTRYPOINTS.md) for the complete and authoritative list.

### orchestrate

Orchestrate complex tasks using specialized expert agents.

```json
{
  "name": "orchestrate",
  "description": "Orchestrate a complex task using specialized expert agents",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task": {
        "type": "string",
        "description": "Task description"
      },
      "context": {
        "type": "object",
        "description": "Optional context"
      },
      "maxIterations": {
        "type": "number",
        "default": 3
      }
    },
    "required": ["task"]
  }
}
```

**Example prompts:**

- "orchestrate: Review this code for security vulnerabilities"
- "orchestrate: Explain the architecture of src/agents/"
- "orchestrate: Generate tests for the user service"

### create_expert

Create a specialized expert agent for specific domains.

```json
{
  "name": "create_expert",
  "description": "Create a specialized expert agent",
  "inputSchema": {
    "type": "object",
    "properties": {
      "role": {
        "type": "string",
        "enum": [
          "code_expert",
          "security_expert",
          "architecture_expert",
          "testing_expert",
          "documentation_expert",
          "devops_expert",
          "research_expert",
          "pm_expert",
          "ux_expert"
        ]
      },
      "modelPreference": {
        "type": "string",
        "description": "Preferred model tier"
      }
    },
    "required": ["role"]
  }
}
```

**Available roles:**

- `code_expert` - Code analysis and implementation
- `security_expert` - Security vulnerability detection
- `architecture_expert` - System design and patterns
- `testing_expert` - Test generation and coverage
- `documentation_expert` - API docs and technical writing
- `devops_expert` - CI/CD, deployment, infrastructure
- `research_expert` - Literature review, technique evaluation
- `pm_expert` - Product management, requirements, priorities
- `ux_expert` - User experience, usability, accessibility

### run_workflow

Execute predefined workflow templates.

```json
{
  "name": "run_workflow",
  "description": "Execute a predefined workflow template",
  "inputSchema": {
    "type": "object",
    "properties": {
      "template": {
        "type": "string",
        "description": "Workflow template name"
      },
      "inputs": {
        "type": "object",
        "description": "Workflow inputs"
      },
      "dryRun": {
        "type": "boolean",
        "default": false
      }
    },
    "required": ["template"]
  }
}
```

**Built-in templates:**

- `code-review` - Review code with security focus
- `feature-implementation` - Feature development workflow
- `bug-fix` - Bug diagnosis and fix
- `documentation-update` - Documentation maintenance
- `refactoring` - Code refactoring workflow
- `research-review` - Research paper analysis
- `security-audit` - Security vulnerability audit
- `standards-review` - Standards compliance check
- `test-generation` - Test case generation

### delegate_to_model

Route tasks to the optimal model based on capabilities.

```json
{
  "name": "delegate_to_model",
  "description": "Route a task to the optimal model based on capabilities",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task": {
        "type": "string",
        "description": "Task description"
      },
      "preferredCapability": {
        "type": "string",
        "enum": ["reasoning", "code", "speed", "cost"]
      }
    },
    "required": ["task"]
  }
}
```

**Capability routing:**

- `reasoning` - Complex analysis, architecture decisions
- `code` - Implementation, code generation
- `speed` - Quick responses, simple tasks
- `cost` - Budget-conscious routing

## Configuration

### Server Configuration

Create `nexus-agents.yaml` in your project root:

```yaml
# Model configuration — use latest models from each provider
# Providers: Anthropic (Claude), OpenAI (GPT/o-series), Google (Gemini), Ollama (local)
models:
  default: claude-sonnet-4-6
  tiers:
    fast:
      - claude-haiku-4-5
      - gpt-4o-mini
    balanced:
      - claude-sonnet-4-6
      - gpt-4o
    powerful:
      - claude-opus-4-6
      - o1-pro

# Expert configuration
experts:
  builtin: true
  custom:
    rust_expert:
      prompt: |
        You are an expert in Rust programming.
        Focus on memory safety, ownership, and idiomatic patterns.
      tier: powerful

# Security settings
security:
  sandbox:
    mode: policy # none | policy | container
  allowedPaths:
    - ./
  rateLimit:
    enabled: true
    requestsPerMinute: 60

# Routing configuration
routing:
  enableBudgetFilter: true
  enableTopsisRanking: true
  enableLinUCBSelection: true
  budget:
    tokenBudget: 1000000
    costBudgetUsd: 10.0
```

### Environment Variables

Set API keys for model access:

```bash
export ANTHROPIC_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export GOOGLE_AI_API_KEY="your-key"
```

### MCP Server Arguments

Pass additional arguments in the MCP configuration:

```json
{
  "mcpServers": {
    "nexus-agents": {
      "command": "nexus-agents",
      "args": ["--mode=server", "--config=/path/to/nexus-agents.yaml", "--verbose"],
      "env": {
        "NEXUS_LOG_LEVEL": "debug"
      }
    }
  }
}
```

## Tool Interaction Examples

### Security Review

User: "orchestrate: Review the authentication module for security issues"

Claude uses the orchestrate tool:

```json
{
  "task": "Review the authentication module for security issues",
  "context": { "focus": "security" },
  "maxIterations": 3
}
```

### Code Generation with Routing

User: "Use delegate_to_model to implement a binary search tree"

Claude uses delegate_to_model:

```json
{
  "task": "Implement a binary search tree with insert, search, and delete operations",
  "preferredCapability": "code"
}
```

### Workflow Execution

User: "Run the code review workflow for the changed files"

Claude uses run_workflow:

```json
{
  "template": "code-review",
  "inputs": {
    "files": ["src/auth.ts", "src/api.ts"]
  }
}
```

## Rate Limits

All MCP tools share a single token bucket rate limiter (capacity: 100 tokens, refill: 10 tokens/sec). Each tool call consumes one token.

## Troubleshooting

### Server Not Starting

Check the MCP configuration path and command:

```bash
# Verify nexus-agents is installed
which nexus-agents

# Test manual startup
nexus-agents --mode=server --verbose
```

### Tools Not Appearing

1. Restart Claude Desktop after config changes
2. Check for JSON syntax errors in `mcp.json`
3. Verify the command path is correct

### Authentication Errors

Ensure API keys are set:

```bash
nexus-agents doctor
```

### Debug Mode

Enable verbose logging:

```json
{
  "mcpServers": {
    "nexus-agents": {
      "command": "nexus-agents",
      "args": ["--mode=server", "--verbose"],
      "env": {
        "NEXUS_LOG_LEVEL": "debug"
      }
    }
  }
}
```

## Programmatic MCP Server

Start the MCP server programmatically:

```typescript
import { startStdioServer } from 'nexus-agents';

await startStdioServer({
  name: 'my-nexus-server',
  version: '1.0.0',
});
```

Or with custom configuration:

```typescript
import { createServer, registerTools, startStdioServer } from 'nexus-agents';

const server = createServer({
  name: 'custom-server',
  version: '1.0.0',
});

registerTools(server, {
  enableOrchestrate: true,
  enableCreateExpert: true,
  enableRunWorkflow: true,
  enableDelegateToModel: true,
});

await startStdioServer(server);
```

## Related Documentation

- [CLI Usage](../ENTRYPOINTS.md) - Use nexus-agents from the command line
- [Workflow Templates](./WORKFLOW_TEMPLATES.md) - Create custom automation
- [Agent Development](../development/AGENT_DEVELOPMENT.md) - Build custom agents
