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, ortext/event-streamwhen the client only accepts SSE. - Notifications (e.g.
notifications/initialized) get202 Acceptedwith an empty body. GET /mcpandDELETE /mcpreturn405 Method Not Allowed— the server is stateless and offers no server-initiated stream or session.POST /mcp/sseis 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
S256method 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 type | Credential |
|---|---|
| Claude Code, Claude Desktop, Cursor, Codex, Windsurf | x-api-key: <Truee API key> (or Authorization: Bearer <api key>) |
| ChatGPT, Claude.ai web, Grok | Authorization: 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
| Tool | Purpose |
|---|---|
search_businesses | Natural-language business search (AI query understanding). |
query_businesses | Structured search — faster, no AI parsing. |
get_business | Full profile by business ID or slug. |
list_categories | Category codes for filtering. |
search_businesses
| Parameter | Type | Required | Notes |
|---|---|---|---|
query | string | yes | Natural language or keywords |
city / state / country / area | string | no | Location filters (country is an ISO code, e.g. NG) |
category | string | no | Category code from list_categories |
verified_only | boolean | no | Return only verified businesses |
lat / lng / radius | number | no | Proximity search (radius in km, max 1000) |
limit | number | no | 1–50 (default 10) |
page | number | no | Pagination (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
| Parameter | Type | Required | Notes |
|---|---|---|---|
id_or_slug | string | yes | Business UUID or slug |
include_announcements | boolean | no | Include 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:
| Code | Meaning |
|---|---|
-32700 | Parse error (malformed JSON) |
-32600 | Invalid Request |
-32601 | Method not found / unknown tool |
-32602 | Invalid 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.