Skip to main content
spekoai-mcp is a FastMCP v3 server that makes Speko’s SDKs, skill sheets, and balance queries available to any MCP-aware agent. The knowledge surface (bundled docs, scaffold prompts, recommendation tool) is public; action tools like get_balance forward the caller’s OAuth access token to the Speko API, so there is no shared server-wide credential. A hosted instance lives at https://mcp.speko.ai. You can also run it locally.

​
Connect a client

{
  "mcpServers": {
    "spekoai": {
      "url": "https://mcp.speko.ai/mcp"
    }
  }
}
Python 3.10+. The server speaks MCP over HTTP; configure your client to hit the /mcp path.

​
Surfaces

​
Tools

ToolDescription
search_docsFull-text search over every bundled Speko doc. Returns slug, title, score, snippet. Each slug is readable at spekoai://docs/{slug}.
list_packagesStructured manifest of every Speko package with URIs to its README and SKILLS sheet.
recommended_stackOpinionated stack for one Speko vertical (general, healthcare, finance, legal). Returns packages, tagline, compliance warnings.
scaffold_voice_appNext.js App Router scaffold manifest for a browser voice app. Emits four files, install commands, and env vars.
get_balanceCaller’s current prepaid credit balance. Forwards the OAuth access token to api.speko.ai/v1/credits/balance. Requires OAuth.

​
Resources

Bundled product docs, readable at spekoai://docs/{slug}. Start with spekoai://docs/index for a slug listing. Skill sheets (*-skills) are dense, LLM-oriented references with API surfaces, minimal snippets, and common gotchas. READMEs (*-readme) are the longer prose walkthroughs.
Only public, user-facing packages are bundled. Internal packages (@spekoai/core, @spekoai/providers), the monorepo-level CLAUDE.md, and per-package ROADMAP.md files are excluded on purpose — they cover internal architecture or forward-looking direction.

​
Components

Copy-paste client snippets exposed over MCP with text/plain mime so clients don’t mangle them during re-emission.
  • spekoai://components/react/voice-session — <SpekoVoiceSession> React component wrapping @spekoai/client. Marked 'use client' for Next.js App Router; dynamic-imports the SDK so it stays out of the SSR bundle.

​
Prompts

PromptArgsDescription
scaffold_projectscenario, language?, runtime?Step-by-step scaffold guide. Scenarios: voice_conversation, batch_transcribe, livekit_agent, quickstart. voice_conversation and livekit_agent are TypeScript-only.

​
Auth model

The server holds no long-lived Speko credential. Action tools forward the caller’s OAuth access token — minted by the Speko platform’s Better Auth OAuth provider — straight to the Speko API, which validates the JWT and scopes the call to that user and org. With OAuth configured, an MCP client mints an access token, FastMCP’s OAuthProxy verifies it, and tools like get_balance relay the same JWT to api.speko.ai via Authorization: Bearer <token>. With OAuth unconfigured the server still boots — the knowledge surface stays public — but get_balance raises a ToolError instructing the caller to set the four required env vars.

​
Self-hosting

uv run spekoai-mcp
To enable OAuth-gated tools, set these env vars before launching:
VariableRequired?Description
SPEKOAI_OAUTH_ISSUERyesMust end in /oauth2, e.g. https://platform.speko.ai/api/auth/oauth2.
SPEKOAI_OAUTH_CLIENT_IDyesOAuth client id registered against the platform.
SPEKOAI_OAUTH_CLIENT_SECRETyesReturned once at registration time; store durably.
SPEKOAI_MCP_BASE_URLyesPublic URL of this server — used as the MCP resource URL (RFC 8707).
SPEKOAI_OAUTH_AUDIENCEnoDefaults to ${SPEKOAI_MCP_BASE_URL}/mcp. Must also appear in the platform’s audience allow-list.
SPEKOAI_BASE_URLnoUpstream override, defaults to https://api.speko.ai.
If any of the four required vars are set, they must all be set — build_auth() rejects partial configs at startup.