{
  "markdown": "# spekoai-mcp\n\nFastMCP v4 server for [SpekoAI](https://speko.ai). The hosted endpoint is:\n\n```text\nhttps://mcp.speko.ai/mcp\n```\n\nIt accepts authenticated `POST` requests using either OAuth or a Speko\nPlatform API key. Configure the URL and let the client negotiate the protocol;\ndo not add protocol headers by hand:\n\n```text\nAuthorization: Bearer <OAuth access token or sk_live_xxx>\nContent-Type: application/json\n```\n\nThe transport is stateless and JSON-only. Modern clients use MCP `2026-07-28`\ndirectly; handshake-era clients such as Cursor negotiate MCP `2025-11-25`\nthrough `initialize`. Both paths remain sessionless: there is no\n`Mcp-Session-Id`, SSE response, local OAuth transaction store, or stdio\ntransport. Better Auth owns authorization, consent, refresh tokens, and client\nregistration; the MCP service only validates signed access tokens per request.\n\n## Client setup\n\nUse the direct-HTTP installer and select OAuth (the default interactive choice):\n\n```bash\nnpx @spekoai/mcp@latest init\n```\n\nOr configure an OAuth-capable client directly. For example, Codex reads:\n\n```toml\n[mcp_servers.speko]\nurl = \"https://mcp.speko.ai/mcp\"\n```\n\nFor automation, export a Platform API key and add the bearer setting:\n\n```toml\n[mcp_servers.speko]\nurl = \"https://mcp.speko.ai/mcp\"\nbearer_token_env_var = \"SPEKO_API_KEY\"\n```\n\n## Tool surfaces\n\nHosted tool surfaces are bound to hostnames; a `profile` query parameter is\nignored. The primary endpoint exposes operational tools using domain/action\nnames:\n\n- account: `organization.get`, `credits.balance.get`,\n  `credits.ledger.list`, `usage.summary.get`;\n- agents: `agents.list`, `agents.preview_stacks`, `agents.create`,\n  `agents.get`, `agents.update`, `agents.delete`, deployment/version/tool and\n  monitor operations;\n- sessions and calls: create, list, inspect, transcript, recording, and test\n  call operations;\n- phone numbers, knowledge bases, evals, migration helpers, audio helpers, and\n  `docs.search`.\n\n### Builder profile\n\nApp builders use the curated host at:\n\n```text\nhttps://builder-mcp.speko.ai/mcp\n```\n\nIt contains docs search, catalogs, agent reads, stack preview, integration code\nsnippets, the test-call review path, and the limited `agents.create` and\n`agents.test_call` writes. Generated applications use Speko SDKs at runtime;\nthey do not call MCP tools.\n\n### Assistant directory hosts\n\nAssistant directories are published on their own hosts, each shaped by that\ndirectory's policy. The surface is a property of the host: there is no query\nparameter, header, or account setting that widens it.\n\n#### Anthropic MCP Directory\n\n```text\nhttps://anthropic.speko.ai/mcp\n```\n\n**32 tools.** Reads across the account, plus speech-to-text:\n\n- account: `organization.get`, `credits.balance.get`, `credits.ledger.list`,\n  `usage.summary.get`;\n- agents: `agents.list`, `agents.get`, `agents.preview_stacks`,\n  `agents.versions.list`, `agents.tools.list`, `agents.tools.get`,\n  `agents.calls.list`;\n- sessions and calls: `sessions.list`, `sessions.get`,\n  `sessions.transcript.get`, `sessions.recording.get`, `calls.get`,\n  `calls.recording.get`;\n- phone numbers: `phone_numbers.list`, `phone_numbers.get`,\n  `phone_numbers.available.search`;\n- knowledge bases: `knowledge_bases.list`, `knowledge_bases.get`,\n  `knowledge_bases.documents.list`, `knowledge_bases.documents.get`;\n- evals and monitoring: `evals.get`, `agents.monitoring.results.list`;\n- audio: `audio.transcribe`;\n- migration helpers: `migration.workspace.inspect`,\n  `migration.external_config.parse`, `migration.session_config.build`,\n  `migration.briefing.render`;\n- other: `docs.search`.\n\nDeliberately **not** on this host, because each one either produces synthetic\nspeech or arms something that will:\n\n| group | absent |\n| ----- | ------ |\n| audio generation | `audio.synthesize` |\n| live session / call creation | `sessions.create`, `sessions.phone.create`, `agents.test_call` |\n| agent configuration and deployment | `agents.create`, `agents.update`, `agents.deploy`, `agents.rollback`, `agents.tools.create`, `agents.tools.update`, `agents.tools.delete` |\n| knowledge-base writes | `knowledge_bases.create`, `knowledge_bases.documents.create`, `knowledge_bases.documents.delete`, `knowledge_bases.documents.finalize` |\n| phone number provisioning | `phone_numbers.create`, `phone_numbers.update` |\n| bulk or scheduled evaluation | `agents.evals.*`, `agents.monitors.*` |\n| irreversible and outward-facing writes | `agents.delete`, `phone_numbers.delete`, `knowledge_bases.delete`, `share_cards.create` |\n\nConfiguring an agent is equivalent to arming it: a deployed agent speaks on\ninbound traffic with no further tool call. Agent create, update, deploy and\nrollback are therefore withheld alongside the generation tool itself.\n`audio.transcribe` stays because speech-to-text produces no audio and returns\nonly text.\n\nThe last row is cut for a different reason. Deleting removes capability rather\nthan arming anything, so those tools are not covered by the rule above — but a\npublished surface has to be describable in one honest clause, and three\nirreversible deletes plus a creator of public pages meant this one could not be\ncalled a read surface. `phone_numbers.delete` also releases a billed number.\nReads of all four resources stay. Calling a withheld tool on this host returns\n`Unknown tool: '<name>'`, identical to a name that was never registered.\n\n#### OpenAI Plugin Directory\n\n```text\nhttps://chatgpt.speko.ai/mcp\n```\n\n**18 tools.** A separate list, not a reuse of the Anthropic one, because the\ntwo directories forbid different things: OpenAI has no restriction on generated\naudio, so `audio.synthesize` and outbound calling stay, while its rules on\nselling digital goods remove phone-number provisioning and the credits and\nusage reads.\n\n## Authentication and downstream calls\n\nOAuth clients discover Better Auth from the MCP protected-resource metadata.\nBetter Auth issues JWT access tokens bound to the exact MCP resource URL. The\nMCP server verifies their signature, issuer, audience, expiry, and scopes on\nevery request without retaining OAuth or protocol state.\n\nProduct-wide Platform API keys are independently verified with\n`GET /v1/auth/api-key-context` on every request. Speko API tools forward API\nkeys unchanged. For OAuth callers, the MCP service mints a separate 60-second\nJWT bound to the Platform API; it never forwards the client-presented MCP token.\n\nConfiguration:\n\n- `SPEKOAI_API_URL` — Platform API origin, default `https://api.speko.dev`;\n- `SPEKOAI_OAUTH_ISSUER` — Better Auth issuer, for example\n  `https://platform.speko.ai/api/auth`;\n- `SPEKOAI_MCP_BASE_URL` — public MCP origin used to derive the exact resource\n  audience;\n- `SPEKOAI_MCP_DELEGATION_SECRET` — 32+ character secret shared only with\n  Platform for stateless API delegation;\n- `SPEKOAI_MCP_DEFAULT_PROFILE` — deployment-only tool surface served at bare\n  `/mcp` (`builder` | `connector` | `chatgpt` | `customer`). Hosted services\n  set it explicitly; public query parameters never select or override it.\n  Unset preserves the legacy full surface for local and self-hosted use.\n\nSee [docs/fastmcp-v4.md](docs/fastmcp-v4.md) for deployment order, smoke tests,\nand failure diagnosis.\n",
  "bytes": 7213,
  "sha": "f4edf71ce401c5746a6879755181dfd1e7e9770868d87092ff5b26ca961132b5",
  "repo_slug": "spekoai/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_speko_mcp_fd5306b4/readme"
}