MCP Integration with AI Agents

Nexus acts as an MCP (Model Context Protocol) server that can be connected to AI agents like Claude Desktop, Claude Code, VSCode Copilot, and other MCP-compatible tools. This allows these agents to access all the tools configured in your Nexus instance.

MCP tools are specific functions or capabilities that MCP servers expose to AI models. Each MCP server can provide multiple tools, allowing AI assistants to:

• File System Tools: Read, write, and manipulate files
• Database Tools: Query and modify databases
• API Tools: Interact with external services
• Compute Tools: Run calculations or transformations

1. Tool Discovery: Nexus provides a context-aware search tool that allows AI assistants to discover tools using natural language queries
2. Tool Namespacing: Tools from downstream servers are automatically namespaced with their server name (e.g., github__search_code, filesystem__read_file)
3. Intelligent Search: The search tool uses fuzzy matching to find relevant tools across all connected MCP servers
4. Tool Execution: Tools are invoked through the execute tool, which routes the request to the appropriate MCP server
5. Rate Limiting: You can set limits on individual tools to prevent abuse
6. Authentication: Tools inherit authentication from their parent server

MCP prompts are predefined conversation templates or interaction patterns that servers can expose. They help guide AI assistants in common tasks or workflows.

1. Prompt Aggregation: Nexus aggregates prompts from all connected MCP servers during initialization
2. Prompt Namespacing: Prompts are prefixed with their server name (e.g., github__create_pr, docs__explain_error)
3. Prompt Listing: AI assistants can list all available prompts from all servers
4. Prompt Retrieval: Individual prompts can be retrieved using get_prompt with the namespaced name

Example prompts from different servers:

• github__review_code - Template for code review requests
• database__optimize_query - Guide for query optimization
• docs__generate_readme - Template for creating documentation

MCP resources represent data or file-like entities that servers can expose, such as documents, configurations, or data sets.

1. Resource Aggregation: Nexus aggregates resources from all connected MCP servers during initialization
2. Resource Identification: Resources are tracked by their URI and mapped to their originating server
3. Resource Listing: AI assistants can list all available resources from all servers
4. Resource Reading: AI assistants can read resource contents using read_resource with the resource URI

Example resources:

• Configuration files with URIs like file:///config/database.yml
• Documentation with URIs like https://docs.example.com/api-guide
• Data sets with URIs like data://analytics/monthly-report
• Templates with URIs like template://project/structure

When you configure multiple MCP servers:

[mcp.servers.github]
url = "https://api.github.com/mcp"

[mcp.servers.filesystem]
cmd = ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home"]

The AI assistant can discover and use:

1. Tools: Use search to find tools, then execute to run them
2. Prompts: List available prompts for guided interactions
3. Resources: List and read available resources for context

All components (tools, prompts, resources) are automatically namespaced to prevent conflicts and maintain clarity about their origin.

Nexus acts as an OAuth2-protected resource - it validates JWT tokens but does not provide authentication itself. Users must authenticate through their chosen OAuth2 provider (Auth0, Okta, Azure AD, etc.), and the MCP client must handle this authentication flow.

1. User chooses their OAuth2 provider (configured in Nexus)
2. MCP client initiates OAuth2 flow with that provider
3. User authenticates with their provider
4. Provider issues JWT token to the MCP client
5. Nexus validates the token using the provider's JWKS endpoint

MCP clients connecting to OAuth2-protected Nexus must:

• Handle OAuth2 authorization code flow
• Store and refresh tokens
• Include valid JWT tokens in requests to Nexus

For a local Nexus instance without authentication, edit claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nexus-local": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp"
      ]
    }
  }
}

Important: Claude Desktop does not support direct OAuth2 configuration in the JSON file. For OAuth2-protected remote servers:

1. Option 1: Use Claude.ai Web Interface

   • Remote servers with OAuth2 can be added through Claude.ai Settings > Connectors
   • Claude handles OAuth2 flow with your provider
   • OAuth callback URL: https://claude.ai/api/mcp/auth_callback

2. Option 2: Use mcp-remote Adapter

   The mcp-remote adapter handles OAuth2 authentication automatically:

   {
     "mcpServers": {
       "nexus": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://nexus.example.com/mcp"]
       }
     }
   }

   When you first use the server, mcp-remote will:

   • Open your browser for OAuth2 authentication
   • Store credentials in ~/.mcp-auth/
   • Handle token refresh automatically

Claude Code has native support for remote MCP servers with OAuth2.

For project-specific configuration:

{
  "servers": {
    "nexus": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Then in Claude Code:

1. Use the /mcp command
2. Select your server
3. Complete the OAuth2 flow in your browser if enabled in Nexus
4. Claude Code handles token management automatically

VSCode's GitHub Copilot also supports MCP servers.

Add to your VSCode user settings (settings.json):

{
  "github.copilot.mcp.servers": {
    "nexus": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Cursor uses the standard MCP configuration format. Add to .cursor/mcp.json (project-specific) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8000/mcp"]
    }
  }
}

For remote servers with OAuth2, simply replace the URL:

• Local: http://localhost:8000/mcp
• Remote: https://nexus.example.com/mcp

The mcp-remote adapter handles both local and remote connections, and will automatically manage OAuth2 authentication when required.