Connect an agent with MCP

MCP is the simplest way to let an agent use HivemindOS managed services. The agent can search the actions available to its key, read data, and run approved work without you writing a separate wrapper for every endpoint.

MCP address: https://api.hivemindos.app/mcp
Transport: Streamable HTTP
Authentication: Authorization: Bearer hmos_live_...

This is the full SuperAgent MCP. The separate Hive Compute MCP remains useful for agents that need only the GPU marketplace.

Connect it

Add a remote HTTP MCP server using your client’s secret or environment-variable feature:

{
  "mcpServers": {
    "hivemindos": {
      "type": "http",
      "url": "https://api.hivemindos.app/mcp",
      "headers": {
        "Authorization": "Bearer ${HIVEMINDOS_API_KEY}"
      }
    }
  }
}

Client formats differ slightly. If your client has an Add remote MCP server screen, enter the address above and add Authorization as a protected header. Do not paste the key into a shared configuration file, prompt, repository, screenshot, or browser application.

An MCP key needs:

• the services:read scope;
• the actions.list operation so the server can authenticate the MCP session and return its action catalog; and
• only the additional scopes, services, and exact operations its job needs.

For example, this operation allowlist can search Cloud Superbrain memory and do nothing else:

{
  "scopes": ["services:read", "services:invoke"],
  "allowedServices": ["cloud-superbrain"],
  "allowedOperations": [
    "actions.list",
    "services.invoke.cloud-superbrain.memory.search"
  ],
  "limits": {
    "services.invoke.cloud-superbrain.memory.search": {
      "requestsPerMinute": 30,
      "maxConcurrent": 3
    }
  }
}

What the agent receives

The MCP exposes four stable tools:

The small tool list keeps agent setup fast even though the API has hundreds of managed actions. Search results are filtered before they reach the agent. A restricted key cannot discover or call an excluded service or operation.

Safe agent instructions

Give the agent these rules:

1. Search before every unfamiliar action. Never invent an actionId.
2. Use hive_read for actions marked read and hive_write for write or execute.
3. Reuse an idempotency key only for the same intended write and the same input.
4. Ask the user before payments, trades, transfers, signatures, deletion, publishing, or another consequential action.
5. Never send a seed phrase, wallet private key, API secret, or unrelated credential as service input.
6. Treat an approval request or HTTP 402 response as a pause for user confirmation, not permission to continue automatically.

The downloadable SuperAgent API skill includes these rules and the complete setup workflow.

Projects and files

A project-bound key always stays in its project. An account-level key can select a project using the MCP connection’s X-HivemindOS-Project protected header or the projectId tool argument.

JSON actions return their normal API result. Binary downloads return an authenticated resource link; fetch it with the same API key. Binary uploads accept bodyBase64 plus a supported file header such as X-File-Name.

Payments and Agent Credits

MCP calls use the same Agent Credit balance, service pricing, endpoint limits, approval rules, and audit trail as REST and the SDK.

To buy Agent Credits with x402, search for credits.x402.topUp, then call it with hive_write. The first call returns the payment challenge. After the user confirms the exact amount, an x402 wallet signs the challenge and the retry sends Payment-Signature with the same idempotency key. The MCP cannot change the recipient, network, asset, price, or credited HivemindOS account.

Advanced: protocol behavior

The endpoint is a stateless Streamable HTTP MCP server. It supports initialize, ping, tools/list, tools/call, notifications, and JSON-RPC batches. Tool annotations explicitly separate read-only and consequential actions. The REST endpoint GET /v1/actions publishes the same key-filtered action catalog for SDK clients and custom agent adapters.

All execution is sent through the normal SuperAgent API request path. Service allowlists, exact operation allowlists, project isolation, per-operation quotas, approvals, idempotency, Agent Credit charging, and downstream service policy remain authoritative; MCP does not create a second permission system.

Continue with authentication and API keys, endpoint limits, or the complete API reference.