MCP Setup

The Nucleus MCP server lets AI assistants read and write your Nucleus data — tasks, projects, clients, people, time, finance, and more — using natural language. It implements the Model Context Protocol over HTTPS with OAuth 2.0.

Claude Desktop

1. Add the server

Open Settings → Developer → Edit Config and add to claude_desktop_config.json:

{
  "mcpServers": {
    "nucleus": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.nucleus.fast/mcp"
      ]
    }
  }
}

Claude Desktop uses stdio transport and proxies to the remote server via mcp-remote (installed automatically by npx).

2. Authenticate

Restart Claude Desktop. On first connect it opens a browser window — sign in with your Dot Collective Google account. You’ll be redirected back and the token is stored locally.

3. Use it

Nucleus tools are now available. Try:

“What tasks are assigned to me this week?”
“Create a task: design review for Apollo, due Friday, assign to me”
“Which clients have no active projects?”

Claude Code (CLI)

Add to ~/.claude/settings.json under mcpServers:

{
  "mcpServers": {
    "nucleus": {
      "type": "http",
      "url": "https://mcp.nucleus.fast/mcp"
    }
  }
}

Or use the CLI:

claude mcp add nucleus --transport http https://mcp.nucleus.fast/mcp

On first use, Claude Code will prompt you to authenticate via browser.

Cursor

Open Settings → MCP → Add new global MCP server and enter:

Name: Nucleus
Type: HTTP
URL: https://mcp.nucleus.fast/mcp

Save and restart Cursor. Authenticate when prompted.

Windsurf / Codeium

Add to your MCP config file:

{
  "mcpServers": {
    "nucleus": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.nucleus.fast/mcp"
      ]
    }
  }
}

What you can do

Once connected, your AI assistant has access to 120+ tools covering the full Nucleus platform:

Read and create tasks, sprints, roadmaps
Query projects, budgets, time entries, resourcing
Look up clients, deals, invoices, contracts
Access people, leave, scorecards, performance reviews
Read meetings, emails, notes, pages
Ask analytical questions with query_nucleus — plain English → SQL → results

All requests are made on your behalf with your Nucleus permissions. Employees see their own data, managers see their squad, heads and executives see everything.

The `query_nucleus` tool

The most powerful tool. Ask any analytical question:

“Which projects ran over budget last quarter?” “Who logged the most time in March?” “Show me all deals stuck in negotiation for more than 3 weeks” “Which clients have no activity in the last 30 days?” “What’s the average deal close time by squad?”

The server converts your question to SQL using Kimi K2.5, executes it read-only against the database, and returns the results. Results are capped at 200 rows and scoped to your access level.

Authentication details

The MCP server is protected by Cloudflare Access with Managed OAuth. Your AI client:

Discovers the auth server via OAuth metadata served by Cloudflare Access
Performs an OAuth 2.1 PKCE flow against Cloudflare Access
You authenticate via Google SSO (your @dotcollective.com.au account)
Cloudflare Access issues a Bearer token (stored locally by your client)

Token lifetime is managed by Cloudflare Access. Your client handles refresh automatically. If refresh fails, you’ll be prompted to re-authenticate.

Troubleshooting

“Invalid or expired token” — Remove and re-add the MCP server in your client to trigger a fresh auth flow. Clear ~/.mcp-auth if using mcp-remote.

Tool not available — You may lack permissions for that module. Check your access level in your Nucleus profile (get_me tool or Settings → Profile).

Wrong data returned — Tools respect your access level. If you expect to see data you can’t, it’s likely a permissions issue rather than a bug.

Tool call fails with 5xx — The Nucleus API or AI service may be briefly unavailable. Retry after a moment.