MCP Integration

The Monogoto Model Context Protocol (MCP) server lets OAuth-capable AI clients work with SIM inventory, connectivity, reports, campaigns, orders, and other Monogoto resources through standard MCP tool calls.

Connect

Use the dedicated production MCP endpoint:

https://mcp.monogoto.io/v1/mcp

Staging:

https://staging.mcp.monogoto.io/v1/mcp

The supported transport for new integrations is Streamable HTTP. Configure the URL in an MCP client and let the client complete the browser-based OAuth flow. Do not send a Monogoto email and password as tool arguments.

Authentication: OAuth 2.0 + PKCE

An unauthenticated request receives HTTP 401 with a WWW-Authenticate challenge that points to protected-resource metadata. Compatible clients use that metadata to discover the authorization server, register when required, and complete an authorization-code flow with PKCE. The client should cache and refresh its OAuth tokens.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="OAuth", resource_metadata="https://mcp.monogoto.io/.well-known/oauth-protected-resource/v1/mcp"

The challenge has no response body. The exact metadata URL is supplied by the live WWW-Authenticate header; clients should follow it rather than construct it. The authorization server advertises authorization-code and refresh-token grants, with S256 as its PKCE challenge method. After authorization, the client sends the resulting access token as a standard OAuth bearer token.

The former access_token and refresh-token tools belonged to the legacy email-and-password/session-token flow. They are not part of the current OAuth-authenticated tool surface. There is therefore no current access-token tool to rename: the reported underscore inconsistency is real in the old documentation, but the correct fix is to remove the obsolete flow rather than introduce an alias.

Client configuration

Claude Code

claude mcp add --transport http monogoto https://mcp.monogoto.io/v1/mcp
claude mcp login monogoto

You can also open /mcp in Claude Code and complete authentication there. Staging uses https://staging.mcp.monogoto.io/v1/mcp.

Claude Desktop and other OAuth-capable clients

Add a remote HTTP MCP server with this URL:

https://mcp.monogoto.io/v1/mcp

Complete the browser sign-in when prompted. Client configuration fields differ by product; use a remote HTTP/Streamable HTTP connection and OAuth rather than embedding credentials or a short-lived bearer token.

MCP Inspector

npx -y @modelcontextprotocol/inspector https://mcp.monogoto.io/v1/mcp

Complete OAuth in the Inspector before listing or calling tools.

Raw JSON-RPC examples

Most developers should use an MCP SDK or client, which handles initialization, OAuth, protocol headers, and token refresh. For protocol debugging, send JSON-RPC to the Streamable HTTP endpoint with the OAuth access token obtained by your client.

Initialize

curl -X POST https://mcp.monogoto.io/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $MONOGOTO_OAUTH_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "my-client", "version": "1.0.0" }
    }
  }'

Use the protocol version negotiated in the initialize response and follow normal MCP lifecycle requirements for your SDK/client.

After receiving the initialize response, send the required notification without an id:

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized",
  "params": {}
}

List tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Call a tool

tools/call requires a params object containing the tool name and an arguments object. params: null is invalid.

curl -X POST https://mcp.monogoto.io/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $MONOGOTO_OAUTH_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "list-things",
      "arguments": { "limit": 10 }
    }
  }'

The arguments object may be empty for tools whose discovered input schema has no required fields, but the surrounding params.name and params.arguments fields are still required.

Tool discovery is authoritative

Call tools/list after authenticating and use the returned names, descriptions, and JSON Schemas. The tool surface evolves independently of the REST API documentation, and access can vary by principal. Do not hard-code a total tool count.

Recent MCP contract changes include:

• Empty-argument tools are callable with "arguments": {}; the former empty-body serialization failure was fixed.
• update-thing performs a partial update: omitted tags are preserved, while an explicit empty tag list clears them.
• Plaintext password and SIM-secret fields are not exposed in the current tool schemas.
• Thing-event report tools require thingId, start_time, and end_time at MCP schema validation.
• Filter tools expose only inputs consumed by their downstream endpoints.
• Top-N reports are consolidated as get-top-report, selected by dimension.
• DNS reports are consolidated as get-dns-report, selected by view.
• NetFlow breakdown reports are consolidated as get-netflow-breakdown, selected by view.
• Data usage reports are consolidated as get-data-usage, with scope-specific identifier validation.
• Superseded report tool names were removed and are not retained as aliases.

These are MCP tool-contract and routing changes. They do not change the underlying MyAccount REST API semantics.

Consolidated report tools

Always inspect each discovered input schema for required time selectors, filters, identifiers, and supported enum values.

Errors

HTTP-level errors

JSON-RPC and tool errors

• Protocol failures use the JSON-RPC error field, such as -32602 for invalid parameters.
• A tool may instead return result.isError: true with error details in its content.
• An old or removed tool name returns a tool-not-found/method error. Rediscover tools rather than guessing a hyphenated alias.

Related guides

• Authentication
• Rate Limits
• Error Reference