Skip to main content

Connect Through MCP

On this page

Connect GPUWorks to an AI client that supports MCP HTTP transport so the client can read node, deployment, and metric information and answer questions about your cluster. When setup is complete, you can list the GPUWorks tools and read a cluster overview.

The client must be able to reach the console address. You need a platform account that can sign in, and an administrator must enable the MCP service. MCP is off by default and provides only read-only tools. The client sends the data it reads to its own configured model. Before connecting, confirm that this model meets your data usage requirements. See Where Data Goes.

Enable the Service

Ask an administrator to open Settings → Security & access, turn on the switch in the MCP service card, and confirm that the status shows On. Note the endpoint shown on the card. If the client and browser run on different machines, confirm that the client can also reach this address.

Platform API Tokens

Go to API Tokens → Platform API tokens, click Create platform token, enter a name, select Read for the scope, choose an expiration period as needed, and click Create. Save the displayed gwp_... token immediately. Its full value appears only once.

This page provides two types of tokens. MCP uses platform API tokens:

Inference tokensPlatform API tokens
Prefixgw-gwp_
Used to call/v1 for deployed models (OpenAI-compatible)Platform management APIs (/api/v1/...) and MCP
Identity and permissionsDoes not represent any userActs as the creator with their current role, further restricted by the token scope

Connect to MCP

The endpoint is https://<console-address>/api/v1/mcp. It uses Streamable HTTP, with a platform API token in the request header. The MCP service card lets you copy a command generated from the browser address. Replace the placeholder token with the full value you just created, and replace the address with an entry point the client can actually reach.

Claude Code:

claude mcp add --transport http gpuworks https://<console-address>/api/v1/mcp \
  --header "Authorization: Bearer gwp_..."

For other clients that support HTTP transport, enter the same endpoint and request header. The following example only illustrates the information you need to pass. Adjust the configuration file location and field format to meet the client's requirements. Pasting this configuration directly is not guaranteed to work in every client:

{
  "mcpServers": {
    "gpuworks": {
      "type": "http",
      "url": "https://<console-address>/api/v1/mcp",
      "headers": { "Authorization": "Bearer gwp_..." }
    }
  }
}

After connecting, confirm that the client can list the GPUWorks tools. Then request a cluster overview and confirm that it calls cluster_overview and returns data from your cluster. Check the tool call result, not just the text generated by the model. If the tools are not listed or the call fails, follow Troubleshooting and try again.

Available Tools

MCP provides the same read-only tools as the console's AI assistant: cluster_overview (cluster overview), search_api / call_api (find and read APIs, with jq support), search_metrics (metric catalog), get_gpu_topology (GPU interconnects), and compare_with_healthy_replica (differences between a failed instance and a healthy replica). The data available is the same as what the token owner can see in the console. Credentials are redacted and results are truncated before the data is handed over, just as in the console. MCP provides no write operations, regardless of the token scope.

get_node_connection_diagnostics can also read connection diagnostics by node UUID, retaining the existing endpoint's administrator permission. It uses a fixed POST path, so the existing method restriction rejects read-only platform tokens; other GET tools remain available. The tool accepts no custom addresses or SSH parameters and performs no recovery or configuration changes.

A user can have at most 4 tool calls running concurrently. Additional calls return a result asking you to try again later. Every tool call writes an mcp tool call entry to the server log, recording the user, token prefix, tool, and duration.

Manage Tokens

Read-only is the default scope. It allows reads from the management API and calls to MCP. Use the read-write scope only when another program actually needs to modify the platform. MCP tools always remain read-only; switching to a read-write token does not add write operations.

Tokens can expire after 30, 90, or 365 days, or never expire. The server stores only a hash. The list shows the last usage time, updated once per minute. If you stop using a client or a token is exposed, sign in to the console and click Revoke in that token's row. Revocation takes effect immediately. To replace a token, create a new one, update and verify the client, and then revoke the old token.

No platform API token can be used to view, create, or revoke tokens. These operations require a signed-in session. If the creator's role changes or their account is deleted, the token's permissions change accordingly or the token becomes invalid.

You can also use a token to call the management API directly without MCP:

curl https://<console-address>/api/v1/nodes -H "Authorization: Bearer gwp_..."

Where Data Goes

The MCP client sends the platform data it reads to its own configured model. The client determines where the data goes, independently of the model configured under Settings → Integrations → AI Services on the platform. If you have concerns about data leaving your country or region, configure the client to use a model you approve, or leave MCP turned off.

Troubleshooting

SymptomCause
403 MCP_DISABLEDThe MCP service is off. Ask an administrator to turn it on in the MCP service card under Settings → Security & access.
401The token is incorrect, revoked, or expired, or its owner's account has been deleted.
403 PLATFORM_TOKEN_READ_ONLYA read-only token was used for a write operation when calling the management API directly. This does not occur in MCP itself.

Was this page helpful?