Connecting Claude Code

Prerequisites

• A Mandraki account with Admin or Member role in your organisation
• Claude Code installed and configured
• Access to Settings > API in the Mandraki web app

Step 1: Create a Service Account

1. Open the Mandraki web app at app.mandraki.cloud.
2. Navigate to Settings > API.
3. Click Create Service Account.
4. Fill in a name (e.g. “Claude Code”) and select type Integration.
5. Click Create.

The service account acts as the identity for your MCP integration. All actions performed through it are attributed to this account in audit logs.

Step 2: Generate an API Token

1. On the service account detail page, click Generate Token.
2. Select the scopes your integration needs. Common choices:

Scope	What it enables
tasks:read	View projects, tasks, and comments
tasks:write	Create, update, complete, and delete tasks
channels:read	List channels, view metadata
channels:history	Read message history
messages:write	Post messages
drive:read	List folders, view and download files
drive:write	Upload files, create folders
calendar:read	View calendar events
calendar:write	Create and update events
users:read	View user profiles
teams:read	List teams and members

3. Optionally set Resource Scopes to restrict access to specific teams, channels, projects, or folders.
4. Optionally set an expiration date.
5. Click Generate.
6. Copy the token immediately — it is shown only once. The token starts with mak_.

Step 3: Configure Claude Code

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "mandraki": {
      "type": "http",
      "url": "https://app.mandraki.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${MANDRAKI_MCP_TOKEN}"
      }
    }
  }
}

Then set the environment variable with your token. Add it to your shell profile (.bashrc, .zshrc) or a .env file:

export MANDRAKI_MCP_TOKEN="mak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Alternative: Inline Token

If you prefer not to use an environment variable, you can put the token directly in the config (not recommended for shared repositories):

{
  "mcpServers": {
    "mandraki": {
      "type": "http",
      "url": "https://app.mandraki.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer mak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Alternative: Claude Code Settings

You can also add the MCP server to .claude/settings.local.json in your project:

{
  "mcpServers": {
    "mandraki": {
      "type": "http",
      "url": "https://app.mandraki.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${MANDRAKI_MCP_TOKEN}"
      }
    }
  }
}

Step 4: Restart Claude Code

After creating the config file and setting the environment variable, restart Claude Code for the changes to take effect. Claude Code reads MCP configuration on startup.

Step 5: Verify the Connection

Once Claude Code restarts, verify the integration is working by asking it something that requires Mandraki data:

• “List my tasks”
• “What channels are in my workspace?”
• “Check my calendar for today”
• “Search messages mentioning the deployment”

Claude Code will discover available tools via tools/list and use them to answer your questions. The tools it sees are limited to the scopes you granted to the API token.

Security Considerations

• Scope minimally. Only grant the scopes your workflow actually needs. You can always add more later by generating a new token.
• Use environment variables. Never commit mak_ tokens to version control. Add .mcp.json to .gitignore if it contains inline tokens, or use ${ENV_VAR} references.
• Resource scopes let you restrict a token to specific teams, channels, projects, or folders. Use these when the integration should only access a subset of your workspace.
• Token rotation. Generate a new token periodically and revoke old ones in Settings > API.
• Audit trail. All tool executions are logged with the service account identity, making it easy to review what the integration has done.

Troubleshooting

”No tools available”

• Verify your token has the correct scopes. A token with no matching scopes returns an empty tool list.
• Check that the service account is active (not deactivated by an admin).
• Ensure the Authorization header is correctly formatted: Bearer mak_... (note the space after “Bearer”).

Connection refused

• Confirm the URL is https://app.mandraki.cloud/api/v1/mcp (not /mcp/ with a trailing slash).
• If you are using a self-hosted Mandraki instance, replace the hostname with your instance URL.

Environment variable not resolved

• Claude Code resolves ${VAR} references from your shell environment. Make sure the variable is exported, not just set.
• Restart your terminal after adding the export to your shell profile.