Skip to content

Model Context Protocol (MCP) Integration

← Integrations | Documentation Index

Expose Nexus to AI agents via the Model Context Protocol (MCP).

Quick Start

# Test the setup (2 minutes)
./examples/mcp/quick_test.sh

# Start MCP server
nexus mcp serve --transport stdio

# With remote Nexus
NEXUS_URL=http://localhost:2026 \
NEXUS_API_KEY=your-key \
nexus mcp serve --transport stdio

Architecture

AI Client (Claude Desktop)
         ↓ MCP (stdio/HTTP)
    Nexus MCP Server
         ↓
Local NexusFS  OR  Remote Nexus Server

Two Modes: - Local: MCP → Local filesystem (personal use) - Remote: MCP → Remote Nexus server (team use, authenticated)

Claude Desktop Setup

Edit ~/.config/claude/claude_desktop_config.json:

Local Mode (No authentication)

{
  "mcpServers": {
    "nexus": {
      "command": "nexus",
      "args": ["mcp", "serve", "--transport", "stdio"],
      "env": {
        "NEXUS_DATA_DIR": "/Users/you/nexus-data"
      }
    }
  }
}

Remote Mode (With authentication)

{
  "mcpServers": {
    "nexus": {
      "command": "nexus",
      "args": ["mcp", "serve", "--transport", "stdio"],
      "env": {
        "NEXUS_URL": "http://localhost:2026",
        "NEXUS_API_KEY": "sk-your-api-key"
      }
    }
  }
}

Setup: 1. Edit config file 2. Completely quit and restart Claude Desktop 3. Try: "List files in /workspace"

Available Tools (14 total)

File Operations

  • nexus_read_file - Read file content
  • nexus_write_file - Write file content
  • nexus_delete_file - Delete file
  • nexus_list_files - List directory
  • nexus_file_info - Get file metadata
  • nexus_mkdir - Create directory
  • nexus_rmdir - Remove directory
  • nexus_glob - Pattern search (**/*.py)
  • nexus_grep - Content search (regex)
  • nexus_semantic_search - Natural language search

Memory

  • nexus_store_memory - Store agent memory
  • nexus_query_memory - Query memories

Workflows

  • nexus_list_workflows - List workflows
  • nexus_execute_workflow - Run workflow

Usage Examples

Basic Operations

Ask Claude Desktop: 

Read the file at /workspace/data.txt


Find all Python files related to authentication

Memory

Remember that our API uses JWT tokens

Authentication

MCP server is a thin protocol adapter - authentication happens on the Nexus server.

Local Mode

  • No API key needed
  • User context from environment: NEXUS_SUBJECT=user:alice
  • All operations run as that user

Remote Mode

  • API key required: NEXUS_API_KEY=sk-...
  • Nexus server validates key and maps to user
  • ReBAC enforced on server side

Architecture: 

Claude Desktop
    ↓ (with NEXUS_API_KEY)
MCP Server (passes api_key through)
    ↓
Nexus Server (validates key, enforces ReBAC)

Deployment Patterns

Personal Use

# Claude Desktop config with local data
{
  "env": {
    "NEXUS_DATA_DIR": "/Users/alice/nexus"
  }
}

Team Use - Option 1: Separate Instances

# Alice's Claude Desktop
{"env": {"NEXUS_URL": "...", "NEXUS_API_KEY": "alice-key"}}

# Bob's Claude Desktop
{"env": {"NEXUS_URL": "...", "NEXUS_API_KEY": "bob-key"}}

Each user's API key determines their permissions via Nexus server's ReBAC.

Team Use - Option 2: Shared HTTP MCP

Start MCP server with HTTP transport: 

nexus mcp serve --transport http --port 8081

Note: HTTP multi-user needs per-request auth (see Authentication Concepts)

Troubleshooting

"Command not found: nexus"

pip install nexus-ai-fs

"Module 'fastmcp' not found"

pip install fastmcp

Claude Desktop Not Showing Tools

  1. Check config file path (macOS: ~/.config/claude/claude_desktop_config.json)
  2. Verify JSON syntax
  3. Completely quit Claude Desktop (not just close window)
  4. Restart Claude Desktop

Tools Returning Errors

  1. Check paths are absolute (/workspace/file.txt not workspace/file.txt)
  2. Verify API key if using remote mode
  3. Check Nexus server logs for auth/permission errors

MCP Server Not Starting

# Test manually
nexus mcp serve --transport stdio

# Check help
nexus mcp --help

Advanced

Python Client Example

from mcp import ClientSession
from mcp.client.stdio import stdio_client

# Connect to Nexus MCP server
server_params = StdioServerParameters(
    command="nexus",
    args=["mcp", "serve", "--transport", "stdio"],
    env={
        "NEXUS_URL": "http://localhost:2026",
        "NEXUS_API_KEY": "your-key"
    }
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()

        # List available tools
        tools = await session.list_tools()
        print(f"Available tools: {[t.name for t in tools.tools]}")

        # Call a tool
        result = await session.call_tool("nexus_read_file", {
            "path": "/workspace/data.txt"
        })
        print(result.content)

Custom Transport

# HTTP transport (for web clients)
nexus mcp serve --transport http --host 0.0.0.0 --port 8081

# SSE transport
nexus mcp serve --transport sse --port 8081

Environment Variables

  • NEXUS_DATA_DIR - Local data directory (local mode)
  • NEXUS_URL - Remote server URL (remote mode)
  • NEXUS_API_KEY - API key for authentication (remote mode)
  • NEXUS_SUBJECT - User context (local mode, e.g., user:alice)

CLI Reference

See MCP CLI Documentation for complete command reference.

Examples

See examples/mcp/ for: - quick_test.sh - Full authentication test (~2 minutes) - demo_mcp_auth_concept.sh - Authentication architecture explained - verify_mcp_tools.py - Verify MCP installation

Resources