---
title: "Developers: Believe Global API and MCP"
description: "Operate Believe Global from your agent: MCP server, REST endpoints and OpenAPI 3.1 spec. No API keys. Quickstart, errors and limits."
canonical: https://believe-global.com/en/developers
language: en
updated: 2026-10-23
---

# Operate Believe Global from your agent.

_Developers · Believe Global API and MCP_

Three surfaces over one backend: an MCP server for agents, REST endpoints for applications, and an OpenAPI 3.1 spec to generate clients. No API keys. Every endpoint is public and applies usage limits.

## Quickstart

1. Ask a question. It is read-only and has no side effects.

```bash
curl -X POST https://believe-global.com/ask \
  -H 'content-type: application/json' \
  -d '{"query": "Is Believe Global a good fit for a LATAM retail brand?"}'
```

2. List the MCP tools.

```bash
curl -X POST https://believe-global.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

3. Call a tool.

```bash
curl -X POST https://believe-global.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ask_brand","arguments":{"query":"Who is Believe not a good fit for?"}}}'
```

4. Submit a diagnostic request. This sends a real email to the Believe team and a confirmation to the address you provide, so use your own details.

```bash
curl -X POST https://believe-global.com/api/v1/contact \
  -H 'content-type: application/json' \
  -d '{"name":"Ana Pérez","email":"ana@example.com","company":"Example Retail","role":"Head of Marketing","country":"CO","context":"Mid-market retail brand with sales data, looking to make marketing operable by agents."}'
```

## Connect an MCP client

Point any MCP client with Streamable HTTP transport at https://believe-global.com/mcp (protocol 2025-06-18, JSON responses, no authentication). Discovery files: /.well-known/mcp.json and /.well-known/mcp/server-card.json. In Claude Code, connect with: claude mcp add --transport http believe-global https://believe-global.com/mcp. GET /mcp returns a descriptor with the tools, the limits and this quickstart.

- `ask_brand`: Read-only retrieval over the signed brand profile: verifiable claims with linked proofs and boundaries. You synthesize the answer.
- `request_diagnostic`: Applies for a diagnostic on behalf of a person. A human replies within 48 hours.
- `apply_partner_program`: Applies to the MAAS Partner Program on behalf of an agency or consultant. A human replies within 48 hours.

## Authentication and limits

No authentication and no API keys. /ask allows 60 requests per minute per client. The REST forms allow 10 submissions per hour per client. The MCP allows 60 requests per minute and 5 submitted actions per hour per client, plus a shared cap of 20 submitted actions per hour. Failed validations do not count. Every response carries RateLimit-Policy, RateLimit and RateLimit-Limit, -Remaining and -Reset headers, so you can self-throttle before you hit the limit. Over the limit you get HTTP 429 with a Retry-After header in seconds. To automate submissions, use the MCP: the REST endpoints are the same forms the website uses.

Rate limit headers on every response:

```http
HTTP/2 200
api-version: 1
ratelimit-policy: "default";q=60;w=60
ratelimit: "default";r=57;t=48
ratelimit-limit: 60
ratelimit-remaining: 57
ratelimit-reset: 48
```

## Versioning and deprecation

The REST endpoints live under /api/v1 and every response carries an API-Version header. /api/contact and /api/partners are aliases pinned to v1. /ask follows the NLWeb convention and /mcp follows the MCP protocol version (2025-06-18). Breaking changes ship only in a new major version (/api/v2). A deprecated version keeps working for at least 180 days: its responses carry a Deprecation header (RFC 9745) with the announcement date, a Sunset header (RFC 8594) with the end date, and a Link header with rel="deprecation" pointing to the notice. Nothing is deprecated today.

## Idempotency

Send an Idempotency-Key header (or idempotency_key in the MCP tools) on the two submission operations, so a retry after a network failure does not submit twice. Use a unique value per operation, for example a UUID, and reuse it only to retry that same call. With the same key and the same body you get the original response with Idempotent-Replayed: true, and the retry does not use your submission quota. The same key with a different body returns 422, and the same key while the first request is still running returns 409. Only successful responses are stored, for 24 hours, so a failed request can be retried with the same key.

## Errors

REST endpoints return JSON with ok, error, code and hint, and issues when validation fails. The MCP returns JSON-RPC errors (-32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32000 rate limit) and reports tool failures with isError.

```json
{
  "ok": false,
  "error": "Revisa estos campos — email: Invalid email address",
  "code": "validation_error",
  "hint": "Fix the fields listed in issues and resend. Schema: https://believe-global.com/openapi.json",
  "issues": ["email: Invalid email address"]
}
```

| Code | HTTP | When |
| --- | --- | --- |
| `validation_error` | 400 | A field is missing or invalid. See issues. |
| `invalid_request` | 400 | The body is not valid JSON or form data. |
| `missing_query` | 400 | The request has no query. |
| `invalid_idempotency_key` | 400 | The Idempotency-Key is not 1 to 255 visible ASCII characters. |
| `not_found` | 404 | There is no API endpoint at that path. |
| `method_not_allowed` | 405 | Wrong HTTP method. See the Allow header. |
| `idempotency_in_progress` | 409 | A request with the same Idempotency-Key is still being processed. Retry with the same key. |
| `idempotency_key_reused` | 422 | The Idempotency-Key was already used with a different request body. |
| `rate_limited` | 429 | Rate limit exceeded. Wait the seconds in Retry-After. |
| `delivery_failed` | 500 | The submission could not be delivered. Retry later. |
| `not_configured` | 503 | The retrieval backend is unavailable. |

## Sandbox

There is no sandbox. ask_brand and /ask are read-only, so use them to test an integration without side effects. request_diagnostic, apply_partner_program and the two REST forms are real submissions.

## WebMCP

An agent in a browser with WebMCP support can use the site directly. Every page registers the read-only ask_brand tool with document.modelContext.registerTool(). The free AOS audit form on the home page is a declarative tool (run_aos_audit): the agent fills the fields and the person reviews and submits it. The submission tools are not exposed through WebMCP: use the MCP for those.

## Machine-readable resources

- [OpenAPI 3.1](https://believe-global.com/openapi.json)
- [Markdown home](https://believe-global.com/index.md)
- [API catalog (RFC 9727)](https://believe-global.com/.well-known/api-catalog)
- [AI catalog (ARD)](https://believe-global.com/.well-known/ai-catalog.json)
- [Agent skills index](https://believe-global.com/.well-known/agent-skills/index.json)
- [API status](https://believe-global.com/api/v1/status)
- [MCP](https://believe-global.com/.well-known/mcp.json)
- [MCP server card](https://believe-global.com/.well-known/mcp/server-card.json)
- [A2A agent card](https://believe-global.com/.well-known/agent-card.json)
- [Brand profile](https://believe-global.com/.well-known/brand.json)
- [llms.txt](https://believe-global.com/llms.txt)
- [AGENTS.md](https://believe-global.com/AGENTS.md)

Questions, or something missing? Write to hola@believe-global.com.