MCP Setup Guide

The Model Context Protocol (MCP) lets AI assistants query and manage your team data through a standardised interface of tools, resources, and prompts. This guide covers how to enable MCP and connect popular AI clients.

Prerequisites

Before connecting an AI assistant:

1. You must be a team owner to enable MCP
2. MCP must be enabled in Settings > MCP
3. For clients other than Claude.ai, you need an API key from Settings > Developer > API Keys

Enable MCP

Connect your AI assistant

Claude.ai

Claude.ai connects via OAuth — no API key is required.

Claude Code (CLI)

Run this command in your terminal:

claude mcp add --transport http shocking-energy YOUR_MCP_ENDPOINT \
  --header "Authorization: Bearer YOUR_API_KEY"

Replace:

• YOUR_MCP_ENDPOINT with the MCP endpoint URL from Settings > MCP
• YOUR_API_KEY with your API key from Settings > Developer > API Keys

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "shocking-energy": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "YOUR_MCP_ENDPOINT",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Config file location:

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

If your MCP endpoint uses http:// (local development), add --allow-http after the endpoint URL.

Cursor / Other MCP clients

Add to your .cursor/mcp.json or the MCP settings in your editor:

{
  "mcpServers": {
    "shocking-energy": {
      "url": "YOUR_MCP_ENDPOINT",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

This configuration works with any MCP client that supports HTTP Streamable transport.

Available tools

MCP exposes tools organised by resource. Each tool includes annotations that tell AI clients whether a tool is read-only, writes data, or is destructive.

Jobs

Scope: jobs.read / jobs.write

Flows

Scope: flows.read / flows.write

Metrics

Scope: metrics.read

Search

Scope: search.read

Team

Scope: team.read

Assets

Scope: assets.read / assets.write

Projects

Scope: projects.read / projects.write

Invoices

Scope: invoices.read / invoices.write

Tool annotations

Every tool includes annotations that help AI clients assess safety:

AI clients like Claude use these annotations to decide whether to ask for confirmation before calling a tool. Read-only tools can be called freely, while write and destructive tools prompt for approval.

Two-phase confirm flow

Some destructive tools — currently flows_fix — use a server-enforced two-phase confirm. This protects against prompt-injection or tool-misuse paths where the AI is tricked into mutating data without operator review.

How it works

What gets refused

The dashboard chat widget threads the confirmToken through automatically — the operator just clicks a button. AI clients calling MCP directly need to plumb the token themselves.

Caller identity

flows_fix records the actor for audit:

• JWT / OAuth callers — the action is always attributed to the authenticated caller. The userId argument is ignored on this path (prevents actor spoofing).
• API-key callers — must pass userId explicitly (no auth user available on API-key calls). The user is resolved by name, email, or ID.

Resources

MCP resources provide static team data through the resources/read protocol method. Resources are cheaper than tool calls for data that rarely changes.

All resources require the team.read scope.

Prompts

MCP prompts are pre-built analysis templates available via the prompts/get protocol method. They guide AI assistants through multi-step analysis workflows.

Using prompts

Ask your AI assistant to use a prompt by name:

"Run the job health check for the last 7 days"

"Give me a daily operations summary for today"

The AI assistant will fetch the prompt template from the MCP server and use it to structure its analysis.

Security best practices

• Start with read-only access — create API keys with apis.read scope first, then add write scopes only when needed
• Scope by domain — use assets.*, projects.*, and invoices.* scopes for least-privilege integrations
• Use dedicated keys per integration — create a separate API key for each AI client so each can be revoked independently
• Review tool calls — destructive tools (cancel, abort) require write scope and AI clients will ask for confirmation
• Rotate keys regularly — revoke and recreate API keys periodically
• Use OAuth for third-party access — OAuth tokens are time-limited and can be revoked by the user at any time

Troubleshooting