NotFair API reference

NotFair connects agents to Google Ads, Meta Ads, X Ads, LinkedIn Ads, Google Search Console, Google Analytics 4, GoHighLevel, and WordPress. Its public integration API uses Model Context Protocol (MCP) over Streamable HTTP. The server URL is:

https://notfair.co/api/mcp/notfair

The NotFair MCP overview is a web page. Send protocol messages to the API endpoint above. Available capabilities depend on the workspace's connected accounts, granted permissions, and enabled integrations. WordPress requires a verified website with the NotFair WordPress Plugin and MCP enabled.

API schemas and discovery

• NotFair OpenAPI specification: HTTP operations, request types, authentication, and response schemas.
• NotFair MCP server card: public compact tool names, descriptions, JSON Schemas, and annotations generated from the runtime registrar.
• OAuth protected resource metadata and authorization server metadata.
• NotFair agent index and public sitemap.

Authentication

Connect a platform in your NotFair workspace, then add the server URL to an MCP client that supports OAuth. NotFair uses the authorization code flow with PKCE (S256). Discover the OAuth endpoints from the metadata above and include the MCP resource URL in the authorization and token requests. The client stores a workspace bearer token and sends it in the Authorization header. Never send upstream platform credentials to tools.

Use one origin throughout discovery and authorization. Both notfair.co and www.notfair.co support existing MCP connections; the OAuth callback issuer must exactly match the issuer first discovered. The new-connection URL uses notfair.co.

Initialization is available without a token. Runtime tools/list and tools/call require authentication; the public server card provides metadata for scanners. Read the NotFair authentication guide for connection recovery.

Example requests

Check the public HTTP heartbeat. This does not check the health of your platform credentials:

curl https://notfair.co/api/health

Start the MCP handshake. The Accept header must include both JSON and server-sent events:

curl https://notfair.co/api/mcp/notfair \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"notfair-example","version":"1.0.0"}}}'

Use an MCP SDK for ongoing requests: send notifications/initialized, use the negotiated MCP-Protocol-Version header, and preserve Mcp-Session-Id if one is returned. After OAuth, list tools with Authorization: Bearer followed by your workspace token. A missing or invalid token returns HTTP 401 and a WWW-Authenticate challenge linking to resource metadata.

Discover and call capabilities

The compact tools are search, executeRead, and execute. Search for the requested task first. The result supplies the capability ID, exact argument schema, and appropriate executor. Read results before proposing a write, explain the change, and obtain the user's authorization before execution.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "list connected accounts"
    }
  }
}

Capabilities differ by integration: advertising platforms expose reporting and supported campaign changes; Search Console includes search performance and sitemap management; GA4 includes reports and supported measurement configuration; GoHighLevel includes CRM reads and writes; WordPress includes website content and management operations. Search returns the capabilities available for the current connection.

Quotas, errors, and retries

Workspace roles, platform permissions, and plan quotas apply to tool execution. See current pricing and operation limits. An HTTP 200 MCP response can still contain a JSON-RPC error or a tool result with isError=true. Inspect the complete response. Reconnect when instructed; do not repeatedly retry a permission or quota error. Before retrying a write, inspect its outcome to avoid duplicate changes.

Markdown and command-line access

Public pages support Accept: text/markdown with quality-value negotiation, Vary: Accept, Accept-Encoding, and a recovery body for missing pages. Browser and application navigation keep their existing HTML and React responses.

curl -H 'Accept: text/markdown' https://notfair.co/docs/reference/api

NotFair works with MCP-compatible command-line clients. See client setup. References to Claude Code, Codex, or Gemini CLI describe those clients; they are not a separate official NotFair CLI package.