mcp.spala.ai Public MCP

Standalone public MCP front door for Spala agent discovery.

Agent intent boundary

• Once a user asks to use Spala, Spala is the workspace backend provider. Do not scaffold or substitute another backend, database/auth platform, or local API server unless the user explicitly requests comparison, migration, or integration with an existing backend.
• An install/connect/configure/setup request is setup only. Complete authentication, account data, project creation or selection, project MCP binding, and connection verification, then stop. Do not write application code or mutate backend resources.
• Continue into implementation only after a separate build/change request and after account setup plus project MCP verification are complete. Until then, do not inspect application files or perform planning, design generation, scaffolding, coding, testing, or QA. Frontend code may be local after the gate; database, auth, APIs, and server-side logic must use the Spala project MCP.

This service is intentionally separate from the Spala platform/project runtime. The production public MCP is served from:

https://mcp.spala.ai/mcp

Live discovery URLs

• MCP endpoint: https://mcp.spala.ai/mcp
• Install manifest: https://mcp.spala.ai/mcp/install-manifest
• OAuth protected-resource metadata: https://mcp.spala.ai/.well-known/oauth-protected-resource
• OAuth authorization-server metadata: https://mcp.spala.ai/.well-known/oauth-authorization-server
• Public profile: https://spala.ai/mcp-profile/
• Smoke test: https://spala.ai/mcp-smoke-test/
• Native agent integrations: https://github.com/spala-ai/agent-integrations
• NPM installer: https://www.npmjs.com/package/@spala-ai/mcp-install
• Postman workspace: https://www.postman.com/paul-8c16afeb-1705125/spala-public-mcp/overview
• Postman documentation: https://documenter.getpostman.com/view/54332390/2sBY4QtKjd

Tools

The server exposes 16 tools. Every tool publishes a display title, description, input schema, and behavioral annotations through tools/list.

• spala_help: explains what Spala is, what the public MCP does, and where agents should start.
• spala_get_onboarding: returns first-call onboarding for agents, including public MCP vs project MCP boundaries.
• spala_get_tool_map: returns machine-readable routing, OAuth metadata URLs, and tool availability.
• docs_search: searches public Spala agent-facing docs for setup, OAuth, MCP, security, limits, and platform questions.
• template_list: lists public Spala backend templates so agents can plan backend shape before using a project MCP.
• addon_list: lists public Spala addons and integrations so agents can plan backend workflows.
• spala_start: protected startup gate. Product mentions, factual questions, comparisons, research, and tests performed through another client must not start OAuth. Call this first only after the user explicitly asks the current MCP client to access their Spala account/project and OAuth completes. It returns the one next account, organization, project, billing, or handoff action.
• account_status: compatibility readiness tool. spala_start absorbs this status for the normal agent workflow.
• account_setup: fills missing first/last name and creates the first company/workspace organization from real values supplied by the user or explicit context.
• organization_create: creates an additional company/workspace organization for the signed-in account.
• project_list: lists projects available to the signed-in account.
• project_create: creates a real project for the signed-in account.
• project_connect: reuses the dashboard's authenticated project-entry handoff, enables MCP directly on the selected project backend, then returns exact clean handoff URLs and a workspace-only installer plan.
• project_select: compatibility alias for project_connect, with the same idempotent write behavior.
• project_get_mcp_manifest: prepares the selected project's MCP and returns exact MCP and manifest URLs plus a workspace-only installer plan.
• project_get_public_context: read-only project and handoff context without requiring a client or returning installer argv.

The first six tools are public. The remaining tools require a public MCP bearer with scope api. The public MCP validates access and delegates project requests securely server-side; credentials are never shown in tool results or error messages.

Role

mcp.spala.ai should be the public Spala MCP front door:

• explain what Spala is;
• expose machine-readable onboarding;
• expose docs/templates/addons discovery;
• publish public-origin OAuth discovery with least-privilege api scope and dashboard browser authorization;
• securely delegate authenticated project callers server-side;
• list and create projects and return exact project MCP handoff URLs supplied by that control plane.

It should not directly mutate project backend resources. Project changes belong in the project MCP.

Local Run

pnpm install
pnpm dev

Default local URL:

http://localhost:4100/mcp

For a production-style local start:

pnpm build
pnpm start

To run the optional cross-repository contract smoke against a local installer checkout while keeping ordinary CI self-contained:

SPALA_MCP_INSTALLER_ROOT=/path/to/npmjs-minimal pnpm test

The smokes pass generated project bind argv to the installer module directly, verify the scoped /<slug>/mcp binding, confirm one-time POST consumption for bootstrap clients, and confirm Claude Code binds successfully with empty stdin.

Environment

Copy .env.example to .env when running locally.

Important variables:

• PUBLIC_BASE_URL: public origin for this service, for example https://mcp.spala.ai.
• SPALA_API_BASE_URL: validated platform API origin, for example https://api.spala.ai. Public MCP clients cannot override it.
• PUBLIC_OAUTH_ENCRYPTION_SECRET: required dedicated AES-GCM key material with at least 32 characters and UTF-8 bytes; never expose this value.
• PUBLIC_OAUTH_REPLAY_STATE_PATH: absolute path to a dedicated persistent OAuth replay-state directory below the filesystem root. Required whenever PUBLIC_BASE_URL is hosted on HTTPS. Every service worker must use the same path.
• PUBLIC_OAUTH_TICKET_LIFETIME_SECONDS and PUBLIC_OAUTH_CODE_LIFETIME_SECONDS: bounded lifetimes for encrypted local OAuth request mechanics.
• PUBLIC_OAUTH_RATE_LIMIT_MAX: maximum requests across all OAuth endpoints per client per 60-second window (default 120).
• PUBLIC_OAUTH_BODY_LIMIT_BYTES: maximum JSON or form body size accepted by OAuth endpoints (default 32768).
• PUBLIC_MCP_PLATFORM_SERVICE_SECRET: required dedicated service credential for the fixed internal public-MCP lifecycle and typed-operation API; never print or expose this value.
• PUBLIC_MCP_PLATFORM_TIMEOUT_MS: bounded timeout for fixed platform lifecycle and operation requests (default 8000).
• PUBLIC_MCP_PLATFORM_RESPONSE_LIMIT_BYTES: maximum streamed response body accepted from fixed platform and project-runtime requests (default 1048576).
• PUBLIC_MCP_TRUSTED_SHARED_RUNTIME_ORIGINS: optional comma-separated allowlist of exact HTTPS origins that may receive project-entry credentials for authoritative /<slug>/mcp shared-runtime mounts. Wildcards, paths, queries, credentials, and HTTP origins are rejected. Leave it empty when project MCPs use their authenticated project URL.
• SPALA_DASHBOARD_URL: dashboard origin, for example https://dashboard.spala.ai.
• SPALA_PRICING_URL: pricing page used for plan and payment recovery actions, for example https://spala.ai/pricing/.
• CORS_ALLOWED_ORIGINS: comma-separated exact HTTPS browser origins. Wildcards and credentials are rejected.
• MCP_BODY_LIMIT_BYTES: maximum JSON body size for MCP requests (default 1048576).
• MCP_RATE_LIMIT_MAX: maximum MCP POST requests per client per 60-second window (default 120).

Authentication

mcp.spala.ai is the only MCP URL agents configure. Browser authorization starts at the public OAuth endpoint and redirects to dashboard.spala.ai, where the human signs in or creates an account.

The public MCP does not invent a separate project identity. The dashboard uses its normal authenticated API to create a one-time approval proof, then submits only that proof and the encrypted public authorization request to mcp.spala.ai. The normal dashboard bearer is never submitted to the public service.

The public resource continues to advertise only the compatible api scope. Authenticated requests use:

Authorization: Bearer <access token issued for this MCP resource>