Remote MCP

The Remote MCP endpoint lets AI assistants, web clients, and any MCP-compatible application access Solenoid tools over HTTP without a local subprocess.

Unlike the local MCP server (which runs as a subprocess and stores tokens in your OS keychain), Remote MCP is stateless. You provide authentication credentials with each request.

Quick Start

Basic request

curl -X POST https://api.solenoid.systems/mcp \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Claude Desktop configuration

Add Remote MCP to your Claude Desktop config file:

{
  "mcpServers": {
    "solenoid-remote": {
      "url": "https://api.solenoid.systems/mcp",
      "transport": { "type": "http" },
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Replace YOUR_TOKEN_HERE with either:

• An OAuth access token from solenoid.systems/account
• An API key from solenoid.systems/account/keys

Calling a tool

curl -X POST https://api.solenoid.systems/mcp \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "check_tenant_balance",
      "arguments": { "tenantId": "user_123" }
    }
  }'

Authentication

All requests to /mcp require an Authorization: Bearer header.

OAuth tokens are obtained via the OAuth 2.1 + PKCE flow documented in Authentication. Tokens expire after 1 hour and must be refreshed.

API keys provide longer-term access and do not expire. Generate one at solenoid.systems/account/keys.

Auth error responses

Tool Selection

By default, Remote MCP enables all product tools available on your subscription tier. Limit the exposed tools with the tools query parameter:

https://api.solenoid.systems/mcp?tools=meter,relay,witness

Available products

For detailed tool documentation, see MCP Server.

Rate Limits

• Limit: 100 requests per 10 minutes per user
• Scope: per authenticated user (based on token)
• Response: HTTP 429 with Retry-After: 600 header

Limitations

Stateless operation. Each request is independent. No session persistence, no server-side state storage, no request history. Every request must include full authentication.

No server-initiated requests. Remote MCP operates in request/response mode only. No sampling, no push notifications, no long-lived connections. For those features, use the local MCP server via npx @solenoid.systems/mcp.

CORS preflight. OPTIONS requests for CORS preflight are unauthenticated. This allows browsers to complete the CORS flow. Actual requests still require authentication.

Error Codes

MCP protocol errors are returned as JSON-RPC 2.0 error responses within a 200 status code.

Endpoints

Health check (no authentication required):

GET https://api.solenoid.systems/health

Returns { "status": "ok", "service": "solenoid-mcp-remote" }.

MCP protocol (authentication required):

POST https://api.solenoid.systems/mcp
GET  https://api.solenoid.systems/mcp?message=<url-encoded JSON-RPC 2.0>

Links

• Local MCP Server
• Authentication Guide
• API Reference