Technical Reference

MCP Integration Guide

Everything you need to connect an AI agent to Admin Substitute via Model Context Protocol. Discovery, authentication, tool invocation, credit billing, crypto payments, and production patterns.

Quickstart Configs Browse All Tools

Discovery & Endpoints

Admin Substitute exposes standard discovery endpoints that any MCP-aware client can auto-detect.

Endpoint	Purpose
GET /.well-known/mcp-server.json	Registry manifest (Smithery/Glama/mcp.so)
GET /.well-known/agent-card.json	A2A agent card
POST /api/v1/mcp	Main MCP endpoint (JSON-RPC 2.0)
GET /api/v1/mcp	HTTP GET discovery (server/discover)
GET /api/v1/mcp/sse	SSE transport for Claude Desktop / Cursor
GET /api/v1/docs	Human-readable API documentation

Discover available tools

curl https://adminsubstitute.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "server/discover"
  }'

# Returns: server info, capabilities, protocol version, tool count

Authentication

Authenticated tools require an API key passed via the Authorization header. API keys are generated during onboarding and can be scoped to specific domains.

Authenticated MCP request

curl -X POST https://adminsubstitute.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ask_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "leads.list",
      "arguments": { "status": "new", "limit": 10 }
    }
  }'

Scopes: API keys have configurable scopes (leads, quotes, jobs, invoices, settings, analytics, price_book). A tool call outside the key's scopes returns error code -32603.

Tool Invocation

All tool calls use JSON-RPC 2.0 with method: "tools/call". The server is fully stateless — no handshake, no session ID, no initialize required.

Full workflow: Lead → Quote → Job → Invoice

// 1. Create a lead
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"leads.create","arguments":{"name":"Mike Chen","phone":"+61400000002","service":"Bathroom Renovation","suburb":"Paddington"}}}

// 2. Create a quote for the lead
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"quotes.create","arguments":{"leadId":"LEAD_ID","items":[{"description":"Bathroom reno - full","qty":1,"unitPrice":12500}]}}}

// 3. Send quote to client
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"quotes.send","arguments":{"quoteId":"QUOTE_ID","method":"sms"}}}

// 4. Create job from accepted quote
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"jobs.create","arguments":{"quoteId":"QUOTE_ID","scheduledDate":"2026-06-05T08:00:00+10:00"}}}

// 5. Complete and invoice
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"jobs.complete","arguments":{"jobId":"JOB_ID"}}}
{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"invoicing.generate","arguments":{"jobId":"JOB_ID"}}}

Response Headers: Every response includes Mcp-Method, Mcp-Name, and rate limit headers (X-RateLimit-Limit, X-RateLimit-Window) for observability.

Free Tools ($0 — Every Plan)

These tools cost $0 to run — included on every plan, even the free tier. You still pass your Bearer API key (all tools/call requests need one), but these never deduct credits. Discovery methods (server/discover, tools/list) are the only calls that need no auth at all — perfect for research and market analysis before you commit.

Formation

formation.requirements

formation.checklist

formation.funding

formation.demand_hotspots

formation.location_score

Lifecycle

lifecycle.assess_stage

lifecycle.stage_tools

Hiring

hiring.capacity_analysis

hiring.readiness_score

hiring.cost_calculator

hiring.apprentice_workflow

hiring.compliance_check

Funding

funding.scan_eligibility

funding.program_detail

Scaling

scaling.readiness_score

Billing

billing.list_plans

billing.create_checkout

billing.get_portal

Integrations

integrations.available_providers

Wallet & Credits

Every company gets a wallet on creation. Tool calls deduct credits automatically — you only pay for what you use.

Category	Cost	Examples
Free	$0.00	formation., lifecycle., hiring., funding., scaling., billing., wallet.balance
Reads	$0.01	leads.list, quotes.list, jobs.list, analytics.*, clients.list, comms.list
Writes	$0.05	leads.create, jobs.create, comms.send_sms, invoicing.generate, quotes.send

Check wallet balance

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "wallet.balance",
    "arguments": {}
  }
}

// Response includes:
// balanceCents, lifetimeDepositCents, lifetimeSpendCents,
// recentTransactions (with type, amount, tool, timestamp)

Top up wallet via Stripe

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "wallet.deposit",
    "arguments": { "amountCents": 10000, "currency": "aud" }
  }
}

// Returns Stripe PaymentIntent client_secret
// Use with Stripe SDK to complete payment

Crypto Payments

Top up your wallet with cryptocurrency. Admin Substitute accepts USDC, USDT, BTC, and ETH via NOWPayments.

Create crypto deposit

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "wallet.crypto_deposit",
    "arguments": {
      "amountAud": 500,
      "cryptocurrency": "USDC"
    }
  }
}

// Returns:
// - payAddress: wallet address to send crypto
// - payAmount: exact amount in chosen crypto
// - orderId: tracking reference
// Wallet is credited automatically on payment confirmation

Agent-to-Agent Transfers

Transfer credits between company wallets for subcontracting, partnerships, or agent-to-agent commerce. One plumber agent can pay an electrician agent directly through the platform.

Transfer credits to another company

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "wallet.transfer",
    "arguments": {
      "toCompanyId": "target_company_id",
      "amountCents": 25000,
      "description": "Payment for electrical sub-contract - Job #4521"
    }
  }
}

// Both wallets updated atomically
// Full audit trail on both sides

Error Handling

Standard JSON-RPC 2.0 error codes plus custom codes for wallet operations.

Code	Meaning	Action
-32600	Invalid Request	Check JSON-RPC format
-32601	Method Not Found	Use tools/list to check available methods
-32602	Invalid Params / Resource Not Found	Check required arguments
-32603	Scope Denied	API key lacks required scope
-32000	Insufficient Credits	Top up wallet via deposit or crypto
401	Unauthorized	Invalid or missing API key
429	Rate Limited	Check X-RateLimit headers, back off

Rate Limits

Rate limits are per API key, per time window. Limits increase with higher plans.

Plan	Requests/min	Window
Lite	30	60s
Starter	60	60s
Growth	120	60s
Pro	300	60s

Advanced Patterns

Multi-Business Operator Mode

A single agent can manage multiple trade businesses. Use operator tools to switch context between companies.

Switch company context

// List all companies in portfolio
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"operator.get_portfolio","arguments":{}}}

// Switch to a specific company
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"operator.switch_company","arguments":{"companyId":"target_id"}}}

// Now all subsequent calls operate on that company

Webhook Integration

Subscribe to real-time events so your agent reacts to changes without polling.

Subscribe to events

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "webhooks.subscribe",
    "arguments": {
      "url": "https://your-agent.example.com/webhooks",
      "events": ["lead.created", "quote.accepted", "job.completed", "payment.received"]
    }
  }
}

Integration Bridge

Push data to connected third-party services (Xero, Slack, Discord, ClickUp, etc.) via MCP.

Push invoice to Xero

// Check available integrations
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"integrations.list_connections","arguments":{}}}

// Push data to connected service
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"integrations.push_entity","arguments":{"provider":"xero","entityType":"invoice","entityId":"inv_123"}}}

Start Building

Get your agent connected in under 5 minutes with pre-built configs.

Quickstart Configs Business Automation Guide