Skip to main content

MCP Server

Truee exposes a standards-compliant Model Context Protocol server so AI assistants can search verified business data and fetch business profiles as tool calls.

https://api.usetruee.com/mcp

Transport​

/mcp implements the MCP Streamable HTTP transport (protocol versions 2024-11-05 through 2025-11-25). Send JSON-RPC 2.0 over POST:

POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream
  • Responses are application/json, or text/event-stream when the client only accepts SSE.
  • Notifications (e.g. notifications/initialized) get 202 Accepted with an empty body.
  • GET /mcp and DELETE /mcp return 405 Method Not Allowed — the server is stateless and offers no server-initiated stream or session.
  • POST /mcp/sse is deprecated and kept only for backward compatibility.

An informational JSON description (not part of the protocol) is available at:

https://api.usetruee.com/mcp/docs

Connect a client​

Clients that send headers (API key)​

Claude Code, Claude Desktop, Cursor, Codex, and Windsurf can send the AI company API key directly.

{
"mcpServers": {
"truee": {
"type": "http",
"url": "https://api.usetruee.com/mcp",
"headers": { "x-api-key": "YOUR_TRUEE_API_KEY" }
}
}
}
# Claude Code
claude mcp add --transport http truee https://api.usetruee.com/mcp \
--header "x-api-key: YOUR_TRUEE_API_KEY"

Clients that sign in with OAuth​

ChatGPT, Claude.ai custom connectors, and Grok cannot send custom headers. They connect with OAuth 2.1 (authorization code + PKCE). Point the client at https://api.usetruee.com/mcp; the 401 challenge starts the flow automatically.

  • Clients register with Dynamic Client Registration, or use a Client ID Metadata Document URL as their client_id. Both are public clients (no client secret).
  • PKCE is required, and only the S256 method is accepted.
  • Send resource=https://api.usetruee.com/mcp (RFC 8707). The token is only valid for that resource.
  • The scope granted is mcp:use.
POST /api/v1/oauth/register # Dynamic Client Registration (RFC 7591) → client_id
GET /api/v1/oauth/authorize # consent screen (reuses your Truee login)
POST /api/v1/oauth/token # exchange code + code_verifier → access token
POST /api/v1/oauth/revoke # revoke an access or refresh token

Discovery documents:

https://api.usetruee.com/.well-known/oauth-protected-resource
https://api.usetruee.com/.well-known/oauth-authorization-server

Access tokens (mcp_at_…) last 30 days. Refresh tokens (mcp_rt_…) last 180 days; exchange one at the token endpoint with grant_type=refresh_token. Tokens are bound to the signed-in person's Truee AI account, so tool calls use that account's quota and credits.

Authentication​

Client typeCredential
Claude Code, Claude Desktop, Cursor, Codex, Windsurfx-api-key: <Truee API key> (or Authorization: Bearer <api key>)
ChatGPT, Claude.ai web, GrokAuthorization: Bearer <OAuth access token>

/mcp requires credentials. An unauthenticated request returns 401 with a WWW-Authenticate header pointing at the protected-resource metadata and the mcp:use scope.

Get an API key at usetruee.com/ai-companies/signup.

Handshake​

Initialize:

{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": { "name": "my-client", "version": "1.0.0" }
}
}

Response:

{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-06-18",
"capabilities": { "tools": { "listChanged": false } },
"serverInfo": { "name": "truee", "title": "Truee", "version": "1.0.0" }
}
}

Then send the notifications/initialized notification, call tools/list, and call tools/call.

Tools​

ToolPurpose
search_businessesNatural-language business search (AI query understanding).
query_businessesStructured search — faster, no AI parsing.
get_businessFull profile by business ID or slug.
list_categoriesCategory codes for filtering.

search_businesses​

ParameterTypeRequiredNotes
querystringyesNatural language or keywords
city / state / country / areastringnoLocation filters (country is an ISO code, e.g. NG)
categorystringnoCategory code from list_categories
verified_onlybooleannoReturn only verified businesses
lat / lng / radiusnumbernoProximity search (radius in km, max 1000)
limitnumberno1–50 (default 10)
pagenumbernoPagination (default 1)

query_businesses​

Same filters as search_businesses, but uses keywords (required) plus an optional intent (find_business, find_product, find_service).

get_business​

ParameterTypeRequiredNotes
id_or_slugstringyesBusiness UUID or slug
include_announcementsbooleannoInclude active announcements

list_categories​

No parameters. Returns the category codes accepted by category.

Example tool call​

{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "search_businesses",
"arguments": {
"query": "fintech companies in Nigeria",
"country": "NG",
"limit": 10
}
}
}

Response (results are also returned as structuredContent for clients that support it):

{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [{ "type": "text", "text": "{\"query\":\"fintech companies in Nigeria\",\"total\":3,...}" }],
"structuredContent": { "query": "fintech companies in Nigeria", "total": 3, "returned": 3, "results": [] }
}
}

Errors​

Errors follow JSON-RPC 2.0. Tool-level failures are returned as a normal result with isError: true; transport/protocol errors use standard codes:

CodeMeaning
-32700Parse error (malformed JSON)
-32600Invalid Request
-32601Method not found / unknown tool
-32602Invalid params (bad tool arguments)

Authentication failures return 401 (with WWW-Authenticate); quota exhaustion returns 429.

Credits and limits​

Each tool call consumes quota from the authenticated Truee AI account. Natural-language search_businesses uses more credits than structured query_businesses. Limits are set by the account's plan and reset at midnight UTC.