API Reference

Full reference for ByteMCP’s HTTP endpoints and MCP protocol.

Base URL

https://mcp.bytefederal.com

Endpoints

Health Check

GET /health

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "mode": "remote",
  "timestamp": "2024-03-15T14:30:00Z"
}

MCP Discovery

GET /.well-known/mcp-server

Response:

{
  "name": "bytefederal-bitcoin-atm",
  "version": "1.0.0",
  "endpoints": {
    "sse": "https://mcp.bytefederal.com/sse",
    "http": "https://mcp.bytefederal.com/mcp"
  },
  "capabilities": ["tools"],
  "tools": [
    "find_nearest_bitcoin_atm",
    "get_atm_details",
    "check_atm_status",
    "list_atms_by_city"
  ]
}

SSE Connection

GET /sse

Establishes Server-Sent Events connection for MCP communication.

Tool Execution

POST /sse
POST /mcp

Execute MCP tool calls via JSON-RPC.

JSON-RPC Format

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "param1": "value1"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Tool result here"
      }
    ]
  }
}

Error

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid request"
  }
}

Tools Reference

find_nearest_bitcoin_atm

Find ATMs near a location.

Parameters:

Name	Type	Required	Default	Description
location	string	No*	-	Search location
lat	number	No*	-	Latitude
lon	number	No*	-	Longitude
limit	number	No	10	Max results (1-50)
maxDistance	number	No	25	Max distance in miles (1-100)

*Either location OR lat/lon required.

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find_nearest_bitcoin_atm",
    "arguments": {
      "location": "Miami, FL",
      "limit": 5,
      "maxDistance": 10
    }
  }
}

get_atm_details

Get details for a specific ATM.

Parameters:

Name	Type	Required	Description
atmId	number	Yes	ATM identifier

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_atm_details",
    "arguments": {
      "atmId": 456
    }
  }
}

check_atm_status

Check ATM status in an area.

Parameters:

Name	Type	Required	Default	Description
location	string	No*	-	Search location
lat	number	No*	-	Latitude
lon	number	No*	-	Longitude
radius	number	No	10	Search radius in miles

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "check_atm_status",
    "arguments": {
      "location": "Dallas, TX",
      "radius": 15
    }
  }
}

list_atms_by_city

List all ATMs in a city.

Parameters:

Name	Type	Required	Description
state	string	Yes	State code (e.g., “TX”)
city	string	Yes	City name

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_atms_by_city",
    "arguments": {
      "state": "TX",
      "city": "Austin"
    }
  }
}

Error Codes

Code	Message	Description
-32700	Parse error	Invalid JSON
-32600	Invalid request	Invalid JSON-RPC
-32601	Method not found	Unknown method
-32602	Invalid params	Invalid parameters
-32603	Internal error	Server error

Rate Limits

Endpoint	Limit
/health	Unlimited
/sse	5 connections/second
/mcp	10 requests/second

CORS

Allowed origins:

• https://bytefederal.com
• https://*.anthropic.com
• https://*.claude.ai
• http://localhost:3000
• http://localhost:4321

cURL Examples

Find ATMs

curl -X POST https://mcp.bytefederal.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "find_nearest_bitcoin_atm",
      "arguments": {
        "location": "Miami, FL",
        "limit": 3
      }
    }
  }'

Get ATM Details

curl -X POST https://mcp.bytefederal.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_atm_details",
      "arguments": {
        "atmId": 123
      }
    }
  }'

SDK Support

Currently, ByteMCP is accessed via:

• MCP protocol (Claude Desktop, Continue.dev)
• Direct HTTP calls

Future SDKs may include:

• JavaScript/TypeScript
• Python
• Go