Nucleus MCP Server

MCP (Model Context Protocol) server for BioTRUST Nucleus platform. Enables Claude Desktop and Claude Code to interact with Nucleus tools including Ada chatbot, Shopify, Amazon Advertising, and more.

Installation

Via npx (Recommended)

Add to your ~/.claude/mcp.json:

{
  "mcpServers": {
    "nucleus": {
      "command": "npx",
      "args": ["-y", "@biotrust/nucleus-mcp-server"],
      "env": {
        "NUCLEUS_API_KEY": "nuc_dev_your_api_key_here"
      }
    }
  }
}

Via npm (Global Install)

npm install -g @biotrust/nucleus-mcp-server

Then configure ~/.claude/mcp.json:

{
  "mcpServers": {
    "nucleus": {
      "command": "@biotrust/nucleus-mcp-server",
      "env": {
        "NUCLEUS_API_KEY": "nuc_dev_your_api_key_here"
      }
    }
  }
}

Getting Your API Key

1. Log in to Nucleus at https://nucleus.biotrust.com
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Give it a name (e.g., "My Claude Desktop")
5. Select the permissions you need (Ada, Shopify, Amazon Ads, etc.)
6. Copy the API key (you'll only see it once!)
7. Paste it into your ~/.claude/mcp.json configuration

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | NUCLEUS_API_KEY | ✅ Yes | - | Your Nucleus API key | | NUCLEUS_API_URL | No | https://nucleus.biotrust.com/api/mcp-gateway | API gateway URL (override for custom deployments) |

Example Configuration with Custom URL

{
  "mcpServers": {
    "nucleus": {
      "command": "npx",
      "args": ["-y", "@biotrust/nucleus-mcp-server"],
      "env": {
        "NUCLEUS_API_KEY": "nuc_dev_your_api_key_here",
        "NUCLEUS_API_URL": "https://nucleus-staging.biotrust.com/api/mcp-gateway"
      }
    }
  }
}

Available Tools

The tools available to you depend on your Nucleus role and API key permissions:

Ada Chatbot Tools

• ada_get_metric - Retrieve Ada chatbot metrics (CSAT, conversations, etc.)
• ada_search_knowledge - Search Ada knowledge base
• ada_get_conversations - Get recent conversations
• And more...

Shopify Tools

• shopify_get_product - Get product details
• shopify_search_products - Search products by query
• shopify_list_orders - List recent orders
• shopify_get_customer - Get customer details
• And more...

Amazon Advertising Tools

• amazon_ads_get_campaigns - List advertising campaigns
• amazon_ads_get_metrics - Get campaign performance metrics
• And more...

Note: You'll only see tools for the MCP servers you have permission to access.

Usage in Claude Desktop

1. Configure your ~/.claude/mcp.json as shown above
2. Restart Claude Desktop
3. Start a new conversation
4. Claude will automatically discover and use Nucleus tools when relevant

Example conversation:

You: What's our CSAT score this week?
Claude: [Uses ada_get_metric tool to fetch current CSAT]

You: How many orders did we get today?
Claude: [Uses shopify_list_orders tool to check orders]

Usage in Claude Code

Claude Code will automatically detect the MCP server configuration from your ~/.claude/mcp.json file. No additional setup needed!

Troubleshooting

"Failed to connect to Nucleus API"

Cause: Invalid API key or network issue

Solution:

1. Verify your API key is correct
2. Check that you can reach https://nucleus.biotrust.com
3. Ensure your API key hasn't expired or been revoked

"Tool not found"

Cause: You don't have permission for that MCP server

Solution:

1. Log in to Nucleus
2. Check your role permissions
3. Contact your admin to request access to additional MCP servers

"No tools available"

Cause: API key doesn't have MCP_CHAT_ACCESS permission

Solution:

1. Your API key needs at least MCP_CHAT_ACCESS permission
2. Contact your admin or regenerate your API key with proper permissions

MCP server not appearing in Claude Desktop

Solution:

1. Verify ~/.claude/mcp.json syntax is valid JSON
2. Restart Claude Desktop completely
3. Check Claude Desktop logs for errors:
   • macOS: ~/Library/Logs/Claude/
   • Windows: %APPDATA%\Claude\logs\

Development

Local Testing

cd packages/@biotrust/nucleus-mcp-server
npm install
npm run dev

Set environment variables:

export NUCLEUS_API_KEY="nuc_dev_your_key"
export NUCLEUS_API_URL="http://localhost:3001/api/mcp-gateway"
npm run dev

Building

npm run build

Publishing

npm run build
npm publish

Security

• Never commit your API key to version control
• Keep your API key secure - treat it like a password
• Rotate keys regularly - generate new keys periodically
• Revoke compromised keys immediately in Nucleus Settings
• Use minimal permissions - only grant the MCP server access it needs

Support

• Documentation: https://nucleus.biotrust.com/docs
• Issues: Create an issue in the Nucleus GitHub repository
• Email: [email protected]

License

MIT