Connecting to MCTL MCP Server

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

Prerequisites

1. An MCTL account with access to a team workspace
2. An AI client that supports MCP (Claude, Cursor, VS Code, etc.)

Setup

Give your client the server URL, https://api.mctl.ai/mcp, and nothing else. Clients that implement MCP authorization discover the sign-in endpoints, open the MCTL sign-in page in your browser, and keep the session refreshed. Nothing is pasted into a config file. Claude.ai, Claude Code, Claude Desktop, Cursor, VS Code and Gemini CLI work this way today; pick their tab below. MCTL sign-in from Windsurf and Copilot CLI is not enabled yet.

Sign in with MCTL

Give your client the server URL and nothing else. On first use it opens the MCTL sign-in page in your browser and returns to the client on its own. There is no token to copy.

https://api.mctl.ai/mcp

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

Claude.ai → Customize → Connectors → Add custom connector

Remote MCP server URL

https://api.mctl.ai/mcp

OAuth Client ID and Client Secret

Leave both empty: Claude registers itself

Click Add, then Connect — the MCTL sign-in page opens, then you'll be returned to Claude automatically. No token needed.

Run in your terminal

claude mcp add --transport http mctl https://api.mctl.ai/mcp

Then run /mcp inside Claude Code and choose mctl → Authenticate. The MCTL sign-in page opens in your browser. No token needed.

Claude Desktop → Customize → Connectors → Add custom connector

Remote MCP server URL

https://api.mctl.ai/mcp

OAuth Client ID and Client Secret

Leave both empty: Claude Desktop registers itself

Click Connect — the MCTL sign-in page opens in your browser. No token needed. A connector you already added on Claude.ai shows up in Claude Desktop too.

Add to ~/.cursor/mcp.json, or Cursor Settings → MCP → Add server

{
  "mcpServers": {
    "mctl": {
      "url": "https://api.mctl.ai/mcp"
    }
  }
}

Cursor then asks you to sign in to mctl in its MCP settings. The MCTL sign-in page opens in your browser. No token needed.

Create .vscode/mcp.json in your project root

{
  "servers": {
    "mctl": {
      "type": "http",
      "url": "https://api.mctl.ai/mcp"
    }
  }
}

Start the server from the file; VS Code asks to sign in and opens the MCTL sign-in page in your browser. No token needed. Requires a recent VS Code with the GitHub Copilot Chat extension.

Windsurf Settings → MCP Servers → Add

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

MCTL sign-in from Windsurf is not enabled yet. Until it is, connect from Claude Code, Cursor, VS Code or Gemini CLI.

Add to ~/.gemini/settings.json

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

Then run /mcp auth mctl inside Gemini CLI. The MCTL sign-in page opens in your browser. No token needed. The sign-in needs a browser on the same machine, so it does not work over SSH.

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

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

MCTL sign-in from Copilot CLI is not enabled yet. Until it is, connect from Claude Code, Cursor, VS Code or Gemini CLI.

Generic MCP client connection details

# Streamable HTTP transport
# Single endpoint — POST to call tools, GET to open stream

endpoint:   https://api.mctl.ai/mcp
transport:  streamable-http
auth:       MCP authorization (OAuth 2.1, PKCE, dynamic client registration)
discovery:  https://api.mctl.ai/.well-known/oauth-protected-resource

Transport: Streamable HTTP. Any client that implements MCP authorization finds the sign-in on its own from the first 401 response; register the client dynamically and sign in through the browser.

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.

Tokens

The token your client holds is issued by mctl-api when you sign in, and the client refreshes it by itself. See Authentication for the flow.

Troubleshooting

See the Troubleshooting page for common connection issues.