Connecting to MCTL MCP Server

Connect your AI assistant to MCTL to manage infrastructure through natural language.

Prerequisites

1. A GitHub account with access to an MCTL organization
2. An AI client that supports MCP (Claude, Cursor, VS Code, etc.)

Setup

Authenticate with GitHub and get a ready-to-use config for your client.

Get your token

Authenticate with GitHub to get a pre-filled config for your developer client.

Access requires membership in a team workspace.
Not added yet? Request access from your platform admin.

Get your token

Permissions requested: read your username and avatar (read:user) and verified email (user:email).
No access to your code, repositories, or organizations. See our Privacy Policy.

or

Get via CLI: gh auth token

Claude.ai → Settings → Connectors → Add custom connector

Remote MCP server URL

https://api.mctl.ai/mcp

OAuth Client ID

mctl-connector

Client Secret

Leave empty (PKCE)

Click Connect — GitHub will open for sign-in, then you'll be returned to Claude automatically. No token needed.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mctl": {
      "type": "http",
      "url": "https://api.mctl.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_TOKEN"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor Settings → MCP → Add server

{
  "mcpServers": {
    "mctl": {
      "type": "http",
      "url": "https://api.mctl.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_TOKEN"
      }
    }
  }
}

Create .vscode/mcp.json in your project root

{
  "servers": {
    "mctl": {
      "type": "http",
      "url": "https://api.mctl.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:mctlToken}"
      }
    }
  },
  "inputs": [
    {
      "id": "mctlToken",
      "type": "promptString",
      "description": "GitHub token — run: gh auth token",
      "password": true
    }
  ]
}

Requires VS Code ≥ 1.99 with the GitHub Copilot Chat extension.

Windsurf Settings → MCP Servers → Add

{
  "mcpServers": {
    "mctl": {
      "type": "http",
      "url": "https://api.mctl.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_TOKEN"
      }
    }
  }
}

Add to ~/.gemini/settings.json

{
  "mcpServers": {
    "mctl": {
      "httpUrl": "https://api.mctl.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_TOKEN"
      },
      "trust": true
    }
  }
}

Add to ~/.config/github-copilot/mcp.json

{
  "mcpServers": {
    "mctl": {
      "type": "http",
      "url": "https://api.mctl.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_TOKEN"
      }
    }
  }
}

Requires gh copilot extension.

Generic MCP client connection details

# Streamable HTTP transport (MCP spec 2024-11-05)
# Single endpoint — POST to call tools, GET to open stream

endpoint:   https://api.mctl.ai/mcp
transport:  streamable-http
auth:       Authorization: Bearer YOUR_GITHUB_TOKEN

Transport: Streamable HTTP (MCP spec 2024-11-05). Send the Authorization header on every request.

Verifying Connection

After connecting, try a simple command:

"Who am I on MCTL?"

This calls the mctl_whoami tool and returns your identity, organization, and tenant access.

Token Types

MCTL accepts three token types. The API auto-detects the type:

Token format	Type	How to get
No dots (e.g. ghp_abc123)	GitHub PAT	GitHub Settings > Tokens
2 dots, external issuer	Dex JWT	SSO login at ops.mctl.ai
2 dots, self-issued	OAuth JWT	OAuth flow on this page (sign in above)

Troubleshooting

See the Troubleshooting page for common connection issues.