MCP Integration

The Monogoto API exposes a full Model Context Protocol (MCP) server, allowing AI assistants and MCP-compatible clients to interact with your SIM fleet, reports, campaigns, orders, and more — all through natural language or structured tool calls.

Overview

MCP is an open protocol that lets AI models call external tools and read resources over a standardised JSON-RPC 2.0 interface. The Monogoto MCP server runs at:

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

Once connected, an AI client can:

• Query and filter your SIM inventory
• Check connectivity, location, and data session status in real time
• Run usage and NetFlow reports with date/group/network filters
• Browse orders, campaigns, audit logs, and tags No custom code is needed — just point your MCP client at the endpoint and authenticate.

Transports

Two transports are available. Use Streamable HTTP unless your client only supports SSE.

Streamable HTTP

Send a single POST request with a JSON-RPC body:

curl -X POST https://api.monogoto.io/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

SSE Transport

1. Open an SSE connection — you receive an endpoint event with the messages URL
2. POST JSON-RPC messages to that URL, passing ?session_id=<id> from the event

# Step 1 — open SSE stream
curl -N https://api.monogoto.io/v1/mcp/sse \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# → data: {"type":"endpoint","uri":"/v1/mcp/messages?session_id=abc123"}

# Step 2 — send JSON-RPC message
curl -X POST "https://api.monogoto.io/v1/mcp/messages?session_id=abc123" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Authentication

Two authentication methods are supported. The right choice depends on your client type.

Option 1 — Bearer Token

Pass a standard Monogoto JWT in the Authorization header on every request. Best for programmatic clients, backend services, and clients where you can configure custom headers.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Obtain a token from POST /v1/auth/token as described in the Authentication guide.

Option 2 — access_token Tool (Recommended for AI clients)

For clients that cannot set custom HTTP headers (e.g. Claude Desktop via stdio bridge), authenticate inside MCP itself. Call the built-in access_token tool — no Authorization header needed.

Step 1 — Initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "my-client", "version": "1.0.0" }
  }
}

Step 2 — Call the access_token tool

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "access_token",
    "arguments": {
      "username": "your@email.com",
      "password": "your-password"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"success\":true,\"message\":\"Login successful\",\"session_token\":\"a3f9c2...\"}"
    }]
  }
}

Step 3 — Pass the session token in all subsequent requests

x-mcp-session-token: a3f9c2...

The session token is stored server-side in Redis (AES-256-GCM encrypted) with a 4-hour TTL. Before it expires, call the refresh-token tool to silently extend the session.

Session vs Bearer — summary

Public vs Authenticated Tools

Without any authentication, only two tools are visible on tools/list:

Once authenticated (either method), all 109 tools become available.

Connecting Clients

Claude Desktop

Claude Desktop uses a stdio bridge (mcp-remote) to connect to HTTP MCP servers.

1. Install Node.js if not already installed.

2. Edit claude_desktop_config.json:

{
  "mcpServers": {
    "monogoto": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.monogoto.io/v1/mcp"
      ]
    }
  }
}

3. Restart Claude Desktop.

4. Authenticate — Claude Desktop cannot set custom HTTP headers, so authentication happens via the access_token tool. When you start a conversation, ask Claude:

"Connect to Monogoto using my credentials: user@example.com"

Claude will call the access_token tool, obtain a session token, and use it automatically for the rest of the session.

Cursor

Cursor supports HTTP MCP servers natively via project-level or global config.

Project-level — create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "monogoto": {
      "url": "https://api.monogoto.io/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Global — add to ~/.cursor/mcp.json to make it available in all projects.

Tip: Use a Cursor secret instead of embedding the token directly in the file.

After saving, open Cursor Settings → MCP and confirm monogoto appears with a green status indicator.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "monogoto": {
      "serverUrl": "https://api.monogoto.io/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Restart Windsurf. The Monogoto tools will appear in the Cascade tool panel.

MCP Inspector (Testing & Debugging)

The official MCP Inspector lets you browse tools and make test calls directly from a browser UI — useful for exploring the API before integrating it into a client.

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

In the Inspector UI:

1. Add a request header: Authorization: Bearer YOUR_ACCESS_TOKEN
2. Click Connect
3. Browse the Tools tab and run test calls

Programmatic / Custom Client

For backend services or custom integrations, call POST /v1/mcp directly.

BASE_URL = "https://api.monogoto.io/v1/mcp"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

def mcp_call(method: str, params: dict, request_id: int = 1) -> dict:
    resp = requests.post(BASE_URL, json={
        "jsonrpc": "2.0",
        "id": request_id,
        "method": method,
        "params": params,
    }, headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {ACCESS_TOKEN}",
    })
    resp.raise_for_status()
    return resp.json()

# Initialize session
mcp_call("initialize", {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {"name": "my-service", "version": "1.0.0"},
})

# List active SIMs
result = mcp_call("tools/call", {
    "name": "list-things",
    "arguments": {"status": "ACTIVATED", "limit": 20},
})
print(result)

const BASE_URL = 'https://api.monogoto.io/v1/mcp';

async function mcpCall(method, params, headers = {}) {
  const res = await fetch(BASE_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.MONOGOTO_TOKEN}`,
      ...headers,
    },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
  });
  return res.json();
}

// Get a specific SIM
const result = await mcpCall('tools/call', {
  name: 'get-thing',
  arguments: { id: '8937010000000000000' },
});
console.log(result);

Available Tools

All 109 tools are listed below. Authenticate first to access them — only access_token and refresh-token are visible to unauthenticated sessions.

Authentication

Things (SIMs & Devices)

Orders & Procurement

Campaigns

Tags

Users

Audit Logs

Reports

NetFlow Reports

Deep traffic analysis — requires NetFlow data to be enabled on your account.

Integrations

Groups

Inbox

Payments

Packet Capture

Rate Plans

SIM Profiles

Rate Limits

Rate limit headers are returned on every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58

When exceeded, the server returns HTTP 429 with a JSON-RPC error body:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32000,
    "message": "Too many requests. Please try again later.",
    "data": { "retry_after": 45 }
  }
}

Read the data.retry_after value and wait that many seconds before retrying.

Error Reference

HTTP-level errors

JSON-RPC errors

These appear in the error field of the response:

Tool-level errors

When a tool fails (e.g. auth error, not found), the response uses isError: true in the result rather than the error field. The content array contains the error detail as JSON text:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"error\":true,\"status_code\":401,\"message\":\"Authentication required. Please call the access_token tool first.\"}"
    }],
    "isError": true
  }
}

This distinction matters: JSON-RPC errors (error field) are protocol failures; tool errors (isError: true in result) are application-level failures from the tool itself.

Related Guides

• Authentication — Obtain a Bearer token for pre-authenticated MCP clients
• Rate Limits — General rate limiting behaviour and retry strategies
• Error Reference — REST API error format (separate from MCP JSON-RPC errors)