Maya MCP Server — Developer Documentation

Overview

The Maya MCP server lets LLM clients (Claude.ai, ChatGPT, Claude Desktop, Cursor, any MCP-compatible tool) query a Maya workspace using the Model Context Protocol. It exposes 24 tools, 3 resources, and 4 slash-command templates behind OAuth 2.1 with scoped access.

• Endpoint: POST https://withmaya.ai/api/mcp/v1/mcp
• Transport: MCP Streamable HTTP (stateless, per-request server instance)
• Server info: name=maya, version=1.0.0
• Auth: OAuth 2.1 with PKCE (preferred) or legacy API key
• Install UI: /app/settings/mcp

Quick install

Paste https://withmaya.ai/api/mcp/v1/mcp into your MCP client's custom-connector form. OAuth handles the rest — your first request triggers a browser sign-in and a consent screen where you approve the scopes.

For step-by-step guides (Claude.ai web, ChatGPT, Claude Desktop), visit /app/settings/mcp.

Authentication

OAuth 2.1 flow (preferred)

1. Client GETs /.well-known/oauth-authorization-server → Authorization Server Metadata (RFC 8414).
2. Client POSTs /api/oauth/register (Dynamic Client Registration, RFC 7591) to receive a client_id. Rate-limited to 20 registrations per IP per hour.
3. Client redirects the user to /api/oauth/authorize with response_type=code, code_challenge_method=S256, a PKCE challenge, scope, and state.
4. User signs in to withmaya.ai (if not already), lands on the consent page at /app/oauth/consent, and approves the scopes.
5. Server issues a one-shot authorization code (10-minute TTL) and redirects the browser back.
6. Client POSTs /api/oauth/token with grant_type=authorization_code, code, code_verifier, redirect_uri. Response: access_token (1 hour TTL), refresh_token (30-day TTL).
7. Client uses the access token as Authorization: Bearer maya_oat_… on every MCP call.
8. Refresh tokens rotate on every use; replay of an already-rotated refresh token revokes the entire chain for that (user, client) pair.

Legacy API keys

Still supported for backward compatibility. Prefix maya_live_…. Hashed with SHA-256 on storage; only the first 14 characters are ever displayed.

Scopes

Tool catalog

Status & narrative (5)

Visibility & competitors (7)

Prompts (5)

Competitor management (2)

Onboarding & self-awareness (8)

Filtering & result conventions

The core query tools (list_prompts, get_citations, get_citation_examples, get_wins_and_losses, get_share_of_voice, compare_competitors) share a consistent set of controls:

• Filters — tool-specific predicates (e.g. domain, sourceType, model, market, language, search, category). The active filter set is echoed back under filter so the caller can confirm what was applied.
• format — "full" (default) returns the rich payload; "compact" returns only the core fields (drops per-model breakdowns, daily series, surrounding context) for a smaller, faster response.
• Pagination — list-shaped tools take limit + offset and return a page block with a stable total and hasMore, so you can page deterministically.
• Sorting — where supported, sortBy + order (asc/desc).
• Caching — read results are cached server-side for ~2 minutes per (tool, project, filter set). Repeated calls in a session are instant; mutations (track_prompt, hide_competitor, unhide_competitor) bust the project's cache so changes surface on the next read.

Resources

MCP resources are pulled by the client at connect time and keep the LLM grounded without explicit tool calls.

Slash-command templates

Available under Claude.ai's "/" menu:

• /maya weekly-report — full 7-day report with tool sequence spelled out.
• /maya briefing — 60-second daily glance, reads resources first.
• /maya competitor-deep-dive — focused drill on a single rival.
• /maya find-seo-gaps — blind-spot discovery across tracked prompts.

Rate limits

• Per token: 300 requests/minute.
• Per workspace: 2 000 requests/minute (sum of all tokens).
• DCR: 20 registrations per IP per hour.

Exceeding any limit returns a tool result with error: "rate_limited", the limit scope, and retryAfterSeconds. Redis outages fail open to keep the product available.

Error envelope

Tool errors come back as MCP CallToolResult with isError: true and a JSON body:

{
  "error": "prompt_already_tracked",
  "message": "This prompt is already being tracked (id: abc, text: \"best CRM for SMB\").",
  "nextAction": "Call get_prompt_result with the existing promptId to see its latest runs, or skip — no action needed."
}

Every error includes a nextAction hint whenever there is one. The LLM is expected to follow the hint before asking the user what to do next.

Versioning

Breaking changes to the protocol or route shape bump the URL path: /api/mcp/v2/…. The previous version stays online for a 90-day deprecation window. Individual tool contracts carry a schemaVersion in the audit log so we can watch adoption before retiring an older shape.

Today we are on:

• MCP server: name=maya, version=1.0.0
• URL path: /api/mcp/v1/mcp

Audit log

Every tool invocation writes one row to mcp_tool_calls with:

• token id (hashed), user id, project id
• tool name, status (ok | error | unauthorized | rate_limited | validation_error)
• latency, input hash, response size, error code
• args_schema_version

Users can query their own activity via Maya's dashboard.

Feedback

Bugs, feature requests, or connector-directory partnerships: [email protected]. Security reports: [email protected].