@xynapse/mcp-server

MCP (Model Context Protocol) server for the Xynapse AI platform. This package exposes all Xynapse tools to MCP-compatible clients like Claude Code.

Features

• ✅ 35+ AI Tools - Access to all Xynapse platform tools
• 🔐 Secure Authentication - Supports API keys and JWT tokens
• 🎯 Role-based Access - Tools filtered by user permissions
• 🔌 Standards Compliant - Implements Model Context Protocol v1.0
• 📦 Easy Integration - Works with Claude Code and other MCP clients

Installation

NPM Package (Recommended for Production)

npm install -g @xynapse/mcp-server

Local Development

cd packages/xynapse-mcp
npm install
npm run build

Quick Start

1. Get Your API Key

Generate an API key from your Xynapse dashboard:

• Navigate to Settings → API Keys
• Click "Generate New Key"
• Copy the key (you'll need it for configuration)

2. Configure Claude Code

Add the following to your Claude Code configuration (~/.config/claude-code/config.json):

{
  "mcpServers": {
    "xynapse": {
      "command": "npx",
      "args": ["@xynapse/mcp-server"],
      "env": {
        "XYNAPSE_API_URL": "https://api.xynapse.com",
        "XYNAPSE_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Start Using Tools

Once configured, Claude Code will automatically discover and use Xynapse tools:

You: Search the web for recent AI news
Claude: [Uses searchWeb tool from Xynapse]

You: Create a new agent for code reviews
Claude: [Uses createAgent tool from Xynapse]

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | XYNAPSE_API_URL | Yes | URL of your Xynapse API (e.g., http://localhost:3000 or https://api.xynapse.com) | | XYNAPSE_API_KEY | Yes* | API key for authentication | | XYNAPSE_TOKEN | Yes* | JWT token for authentication (alternative to API key) |

*Either XYNAPSE_API_KEY or XYNAPSE_TOKEN is required.

Local Development Setup

For local development with xynapse-api running on localhost:3000:

{
  "mcpServers": {
    "xynapse": {
      "command": "node",
      "args": ["/Users/you/xynapse/packages/xynapse-mcp/dist/index.js"],
      "env": {
        "XYNAPSE_API_URL": "http://localhost:3000",
        "XYNAPSE_API_KEY": "your-local-api-key"
      }
    }
  }
}

Available Tools

The MCP server exposes all tools available in your Xynapse instance based on your role:

Shared Tools

• searchWeb - Search the web for information
• getOrganizationInfo - Get organization details

Admin Tools

• createOrganization - Create new organizations
• updateOrganization - Modify organization settings
• manageUsers - User management operations

Agent Tools

• createAgent - Create new AI agents
• listAgents - List available agents
• executeAgent - Run an agent task

Integration Tools

• GitHub: Repository management, PR reviews, issues
• Jira: Issue tracking and project management
• Slack: Send messages and notifications
• Google Calendar: Event management
• Notion: Knowledge base operations
• And many more...

Architecture

┌─────────────┐
│ Claude Code │
└──────┬──────┘
       │ MCP Protocol (stdio)
       │
┌──────▼──────────────┐
│ @xynapse/mcp-server │  (This package)
└──────┬──────────────┘
       │ HTTP/REST
       │
┌──────▼─────────┐
│ xynapse-api    │
│ /mcp/execute   │  (Proxy endpoint with auth)
└──────┬─────────┘
       │
┌──────▼─────────┐
│ ToolsService   │  (35+ tools)
└────────────────┘

How It Works

1. MCP Server runs as a standalone process using stdio transport
2. HTTP Client authenticates and forwards tool calls to xynapse-api
3. Proxy Endpoint validates auth (API key/JWT) and user permissions
4. ToolsService executes the requested tool and returns results
5. Response flows back through the chain to Claude Code

Development

Build

npm run build

Watch Mode

npm run watch

Test Locally

npm run dev

Publishing to NPM

Preparation

1. Update version in package.json
2. Build the package: npm run build
3. Test locally with npm link

Publish

# Login to npm (first time only)
npm login

# Publish package
npm publish --access public

Scoped Package

If publishing as a scoped package (e.g., @xynapse/mcp-server), ensure your npm account has access to the organization.

Troubleshooting

"Invalid API Key" Error

• Verify your API key is correct in the config
• Check that the API key hasn't expired
• Ensure your user account is active

"Tool not found" Error

• Check your user role has access to the tool
• Verify the tool name is spelled correctly
• Try listing available tools: the MCP server logs tools on startup

Connection Refused

• Ensure XYNAPSE_API_URL is correct
• Check that xynapse-api is running
• Verify firewall/network settings

Viewing Logs

The MCP server logs to stderr. To view logs in Claude Code:

• Check the MCP server output in Claude Code's developer tools
• Look for lines starting with [MCPServer], [XynapseClient], etc.

Security

• Never commit API keys to version control
• Use environment variables for all credentials
• API keys are transmitted via x-api-key header
• JWT tokens use Authorization: Bearer header
• All requests are validated by xynapse-api guards

Support

• Issues: GitHub Issues
• Documentation: Xynapse Docs
• Email: [email protected]

License

MIT

Built with ❤️ by the Xynapse team