Totus MCP Server

Totus provides a hosted, remote Model Context Protocol (MCP) server at:

https://api.totus.cloud/mcp

Using the standard Streamable HTTP transport, you can connect AI assistants, coding IDEs, and autonomous agents (such as Claude Code, Claude Desktop, Cursor, Windsurf, or custom MCP clients) directly to Totus's datasets and verification engines—with zero local installation required.

---

Authentication & Credits

Totus MCP supports OAuth 2.1 as the primary, recommended authentication method for all major AI clients and IDEs. For headless systems or legacy web connectors, standard API Tokens (TTT_...) are also supported.

Option A: OAuth 2.1 (Recommended — Zero Token Management)

All major MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf, MCP Inspector) support native OAuth 2.1 discovery via RFC 9728 and RFC 8414 metadata:

• Simply configure the server URL: https://api.totus.cloud/mcp (no API key required).
• On first connection, the client opens your browser to authorize access with one click.
• Totus provisions a stable connection token and rotates credentials weekly in-place. You can view or revoke active connections anytime in the Totus Console under Account > Sessions.

Option B: Static API Token (TTT_...)

For automated scripts, CI/CD runners, or custom services where interactive browser authorization is not possible, you can authenticate using a customer API Token created in the Totus Console:

1. HTTP Authorization Header (Standard for headless & CI/CD):

   Authorization: Bearer TTT_YOUR_API_KEY
2. Query Parameter ?t= (Legacy fallback only):

   https://api.totus.cloud/mcp?t=TTT_YOUR_API_KEY

Security Consideration: Query Parameter Authentication

Passing API tokens via the ?t= query parameter is provided strictly as a legacy fallback for platforms that do not support OAuth 2.1 or custom HTTP headers. Query parameters are routinely recorded in web server access logs, browser histories, and network proxies. We strongly discourage using ?t= wherever OAuth 2.1 or Authorization headers are supported.

• Free Discovery: Connecting to /mcp, negotiating capabilities (initialize), and listing available tools (tools/list) do not consume credits.
• Single Point of Truth Pricing: Credits are only deducted when the AI executes a tool (tools/call), billed at the exact same rate as the underlying REST endpoint.

---

Client Setup

Claude Code (CLI)

Add the Totus MCP server with automatic OAuth 2.1 authentication:

claude mcp add --transport http totus https://api.totus.cloud/mcp

(For headless CI/CD, you may optionally pass --header "Authorization: Bearer TTT_YOUR_API_KEY").

Cursor / Windsurf

Add the following to your .cursor/mcp.json (or equivalent MCP configuration file):

{
  "mcpServers": {
    "totus": {
      "url": "https://api.totus.cloud/mcp"
    }
  }
}

(For headless or manual key authentication, add "headers": { "Authorization": "Bearer TTT_YOUR_API_KEY" }).

Claude Desktop (claude_desktop_config.json)

Configure Claude Desktop using mcp-remote with OAuth 2.1 discovery:

{
  "mcpServers": {
    "totus": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.totus.cloud/mcp"
      ]
    }
  }
}

Legacy Web Connectors (Query Parameter Fallback)

For web platforms that only accept a single URL field and do not support OAuth or custom headers:

https://api.totus.cloud/mcp?t=TTT_YOUR_API_KEY

---

Available Tools

All utility and reference tools are annotated with readOnlyHint: true and destructiveHint: false, allowing MCP clients to execute lookups smoothly.

1. validate_email

Validates an email address across up to 5 progressive inspection levels. Maps to GET /validate/email.

Parameter	Type	Required	Default	Description
email	string	Yes	—	The email address to validate.
level	string	No	l4_dbs	Validation depth: l1_syntax (0.1 cr), l2_dns (1.0 cr), l3_server (1.35 cr), l4_dbs (1.75 cr), or l5_smell (2.25 cr).

• l1_syntax: RFC syntax verification.
• l2_dns: MX records, SPF, DKIM, DMARC, DNSSEC, and Forward-Confirmed reverse DNS (FCrDNS).
• l3_server: Live SMTP server handshake up to RCPT TO and greylisting detection.
• l4_dbs (default): Checks against disposable/temporary email providers and free email domain databases.
• l5_smell: Adds AI heuristic analysis to score address credibility.

---

2. lookup_ip

Retrieves geolocation, ASN/ISP network ownership, and proxy/VPN/Tor threat intelligence for an IPv4 or IPv6 address. Maps to GET /ref/net/ip.

Parameter	Type	Required	Default	Description
ip	string	No	Caller's IP	IPv4 or IPv6 address to inspect (e.g. 8.8.8.8 or 2001:4860:4860::8888). If omitted, resolves the requester's public IP.

Returned fields include: country, cc, region, city, postcode, timezone, lat, lon, elevation, gh (geohash), asn, as, isp, domain, netspeed, usagetype, is_proxy, proxy_type, proxy_fraud_score, and proxy_threat.

---

3. search_nearby_poi

Searches for geographical Points of Interest (POIs) around a coordinate pair (lat & lon) or a geohash (gh), ordered by ascending distance. Maps to GET /ref/geo/poi.

Parameter	Type	Required	Default	Description
lat	number	Cond.	—	Latitude in decimal WGS84 (provide both lat and lon, or gh).
lon	number	Cond.	—	Longitude in decimal WGS84 (provide both lat and lon, or gh).
gh	string	Cond.	—	Geohash center point (alternative to lat and lon, e.g. from lookup_ip).
dist	number	No	1000	Search radius in meters (max 160000 / 160 km).
what	string	No	—	Preset POI category filter (see below).
filter	string[]	No	—	Custom OpenStreetMap tag filters in key=value format. Supports * wildcards and ~ prefix for case-insensitive matching (e.g. ["name=~*starbucks*"]).
limit	integer	No	15	Maximum number of closest POIs to return (1 to 100).

Supported what categories: atm, bank, bus_stop, city, clinic, club, dentist, diplomatic, doctor, embassy, hand_washing, healthcare, hospital, hostel, hotel, laboratory, museum, parking, pharmacy, school, shop, studio, subway, town, train_stop, village, water_station.

---

4. get_balance

Retrieves the current prepaid credit balance for the authenticated account. Maps to GET /balance.

This tool requires no input arguments and is free of charge.

Parameter	Type	Required	Default	Description
(none)	—	—	—	No parameters required.

Returned payload:

{
  "credits": 1234.56
}

---

Example Prompts & Tool Chaining

Because lookup_ip returns lat, lon, and gh (geohash) and search_nearby_poi accepts either gh or lat/lon, AI agents can naturally chain tools together:

• "Check if contact@suspicious-domain.xyz is a disposable email or has valid MX/SMTP servers."
• "Look up the IP 8.8.8.8 and find the 5 closest pharmacies or hospitals within 2 km of its location."
• "Find bakeries named 'Sabores' within 50 km of latitude 8.9752, longitude -79.5147."

---

Testing Directly with curl

You can test the JSON-RPC 2.0 MCP endpoint directly from your terminal:

# 1. List available tools
curl -s -X POST https://api.totus.cloud/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq .

# 2. Call lookup_ip
curl -s -X POST https://api.totus.cloud/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TTT_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "lookup_ip",
      "arguments": {
        "ip": "8.8.8.8"
      }
    }
  }' | jq .

# 3. Call get_balance
curl -s -X POST https://api.totus.cloud/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TTT_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_balance",
      "arguments": {}
    }
  }' | jq .