← ToolOracle Authentication Guide

MCP Authentication

Three ways to use ToolOracle MCP servers: free (no auth), API key (registered), or x402 USDC (pay per call).

Path 1: Free tools — no auth needed

Connect directly

claude mcp add --transport http tooloracle https://tooloracle.io/mcp/

Free tools work immediately. No sign-up, no API key, no payment. 100 calls/day.

Path 2: API key — registered agent

Step 1: Register (free, no auth needed)

Call kya_register via MCP. No API key required for registration.

{
  "method": "tools/call",
  "params": {
    "name": "kya_register",
    "arguments": {
      "agent_name": "My Agent",
      "agent_purpose": "Compliance monitoring",
      "owner_org": "My Company"
    }
  }
}

Returns: client_id, api_key, and 500 welcome units.

Step 2: Use API key

Pass the key via HTTP header on all subsequent calls:

X-API-Key: fo_0fd71a73567514f3...

Units are deducted per tool call. Check balance with kya_status.

Step 3: Top up

Plan	Units/month	Price
Free	500 (welcome)	$0
Pro	1,100	$49/month
Agent	5,500	$299/month
Enterprise	Custom	Contact

Path 3: x402 USDC — pay per call

No registration needed

Send USDC on Base to the gateway wallet. Include the transaction hash in the X-PAYMENT header. Units are auto-credited.

See the full x402 Protocol Reference.

POST /x402/flight/mcp/
X-PAYMENT: 0xe29213362ce2ef08...
Content-Type: application/json

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

Trust levels

Level	Name	Access	Reports
0	UNVERIFIED	Free tools only	No
1	KNOWN	All tools	No
2	TRUSTED	All tools	Yes
3	CERTIFIED	All tools + priority SLA	Yes

Endpoints

Endpoint	Auth	Purpose
`tooloracle.io/mcp/`	API key or free	Main MCP endpoint
`tooloracle.io/x402/{product}/mcp/`	x402 USDC	Pay-per-call endpoint
`tooloracle.io/guard/mcp/`	API key	AgentGuard (20 tools)
`tooloracle.io/.well-known/agent-card.json`	None	A2A Agent Card