[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_119":120},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":55,"_56":-5,"_57":49,"_58":59,"_60":61,"_62":63,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73,"_74":75,"_76":77,"_78":79,"_80":-5,"_81":-5,"_82":83,"_84":49,"_85":-5,"_86":59,"_87":88,"_89":90,"_91":92,"_93":94,"_95":96,"_97":98},"apiUrl","https://odel.app/api","creator","spala-ai","moduleId","spala-public-mcp","@spala-ai/spala-public-mcp","displayName","Spala Public MCP","tagline","Discovery, OAuth, project operations, and exact project MCP handoff for Spala backend projects.","iconKey","https://spala.ai/brand/icon-square-1024.png","category","remote","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://mcp.spala.ai/mcp\",\"transport\":\"streamable-http\",\"authType\":\"headers\",\"requiredSecrets\":[{\"name\":\"ACCEPT\",\"scope\":\"per-user\",\"header\":\"Accept\"}]}","pricingModel","free","creatorUserId","system:external-import","createdAt",1784866701000,"updatedAt",1788322725000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=ai.spala%2Fpublic-mcp","sourceVerified",false,"sourceMissingSince","importedAt","upstreamStars",0,"upstreamUpdatedAt",1788265997000,"detectedTransport","streamable-http","detectedAuthType","none","probeStatus","ok","lastProbedAt",1787631518000,"githubRepoUrl","https://github.com/spala-ai/spala-public-mcp","githubRepoFullName","spala-ai/spala-public-mcp","releaseId","ext-spala-ai-spala-public-mcp","version","1.0.2","descriptionMarkdown","# mcp.spala.ai Public MCP\n\nStandalone public MCP front door for Spala agent discovery.\n\n## Agent intent boundary\n\n- 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.\n- 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.\n- 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.\n\nThis service is intentionally separate from the Spala platform/project runtime. The production public MCP is served from:\n\n```txt\nhttps://mcp.spala.ai/mcp\n```\n\n## Live discovery URLs\n\n- MCP endpoint: `https://mcp.spala.ai/mcp`\n- Install manifest: `https://mcp.spala.ai/mcp/install-manifest`\n- OAuth protected-resource metadata: `https://mcp.spala.ai/.well-known/oauth-protected-resource`\n- OAuth authorization-server metadata: `https://mcp.spala.ai/.well-known/oauth-authorization-server`\n- Public profile: `https://spala.ai/mcp-profile/`\n- Smoke test: `https://spala.ai/mcp-smoke-test/`\n- Native agent integrations: `https://github.com/spala-ai/agent-integrations`\n- NPM installer: `https://www.npmjs.com/package/@spala-ai/mcp-install`\n- Postman workspace: `https://www.postman.com/paul-8c16afeb-1705125/spala-public-mcp/overview`\n- Postman documentation: `https://documenter.getpostman.com/view/54332390/2sBY4QtKjd`\n\n## Tools\n\nThe server exposes 16 tools. Every tool publishes a display title, description, input schema, and behavioral annotations through `tools/list`.\n\n- spala_help: explains what Spala is, what the public MCP does, and where agents should start.\n- spala_get_onboarding: returns first-call onboarding for agents, including public MCP vs project MCP boundaries.\n- spala_get_tool_map: returns machine-readable routing, OAuth metadata URLs, and tool availability.\n- docs_search: searches public Spala agent-facing docs for setup, OAuth, MCP, security, limits, and platform questions.\n- template_list: lists public Spala backend templates so agents can plan backend shape before using a project MCP.\n- addon_list: lists public Spala addons and integrations so agents can plan backend workflows.\n- 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.\n- account_status: compatibility readiness tool. `spala_start` absorbs this status for the normal agent workflow.\n- account_setup: fills missing first/last name and creates the first company/workspace organization from real values supplied by the user or explicit context.\n- organization_create: creates an additional company/workspace organization for the signed-in account.\n- project_list: lists projects available to the signed-in account.\n- project_create: creates a real project for the signed-in account.\n- 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.\n- project_select: compatibility alias for `project_connect`, with the same idempotent write behavior.\n- project_get_mcp_manifest: prepares the selected project's MCP and returns exact MCP and manifest URLs plus a workspace-only installer plan.\n- project_get_public_context: read-only project and handoff context without requiring a client or returning installer argv.\n\nThe 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.\n\n## Role\n\n`mcp.spala.ai` should be the public Spala MCP front door:\n\n- explain what Spala is;\n- expose machine-readable onboarding;\n- expose docs/templates/addons discovery;\n- publish public-origin OAuth discovery with least-privilege `api` scope and dashboard browser authorization;\n- securely delegate authenticated project callers server-side;\n- list and create projects and return exact project MCP handoff URLs supplied by that control plane.\n\nIt should not directly mutate project backend resources. Project changes belong in the project MCP.\n\n## Local Run\n\n```bash\npnpm install\npnpm dev\n```\n\nDefault local URL:\n\n```txt\nhttp://localhost:4100/mcp\n```\n\nFor a production-style local start:\n\n```bash\npnpm build\npnpm start\n```\n\nTo run the optional cross-repository contract smoke against a local installer\ncheckout while keeping ordinary CI self-contained:\n\n```bash\nSPALA_MCP_INSTALLER_ROOT=/path/to/npmjs-minimal pnpm test\n```\n\nThe smokes pass generated `project bind` argv to the installer module directly,\nverify the scoped `//mcp` binding, confirm one-time POST consumption for\nbootstrap clients, and confirm Claude Code binds successfully with empty stdin.\n\n## Environment\n\nCopy `.env.example` to `.env` when running locally.\n\nImportant variables:\n\n- `PUBLIC_BASE_URL`: public origin for this service, for example `https://mcp.spala.ai`.\n- `SPALA_API_BASE_URL`: validated platform API origin, for example `https://api.spala.ai`. Public MCP clients cannot override it.\n- `PUBLIC_OAUTH_ENCRYPTION_SECRET`: required dedicated AES-GCM key material with at least 32 characters and UTF-8 bytes; never expose this value.\n- `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.\n- `PUBLIC_OAUTH_TICKET_LIFETIME_SECONDS` and `PUBLIC_OAUTH_CODE_LIFETIME_SECONDS`: bounded lifetimes for encrypted local OAuth request mechanics.\n- `PUBLIC_OAUTH_RATE_LIMIT_MAX`: maximum requests across all OAuth endpoints per client per 60-second window (default `120`).\n- `PUBLIC_OAUTH_BODY_LIMIT_BYTES`: maximum JSON or form body size accepted by OAuth endpoints (default `32768`).\n- `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.\n- `PUBLIC_MCP_PLATFORM_TIMEOUT_MS`: bounded timeout for fixed platform lifecycle and operation requests (default `8000`).\n- `PUBLIC_MCP_PLATFORM_RESPONSE_LIMIT_BYTES`: maximum streamed response body accepted from fixed platform and project-runtime requests (default `1048576`).\n- `PUBLIC_MCP_TRUSTED_SHARED_RUNTIME_ORIGINS`: optional comma-separated allowlist of exact HTTPS origins that may receive project-entry credentials for authoritative `//mcp` shared-runtime mounts. Wildcards, paths, queries, credentials, and HTTP origins are rejected. Leave it empty when project MCPs use their authenticated project URL.\n- `SPALA_DASHBOARD_URL`: dashboard origin, for example `https://dashboard.spala.ai`.\n- `SPALA_PRICING_URL`: pricing page used for plan and payment recovery actions, for example `https://spala.ai/pricing/`.\n- `CORS_ALLOWED_ORIGINS`: comma-separated exact HTTPS browser origins. Wildcards and credentials are rejected.\n- `MCP_BODY_LIMIT_BYTES`: maximum JSON body size for MCP requests (default `1048576`).\n- `MCP_RATE_LIMIT_MAX`: maximum MCP POST requests per client per 60-second window (default `120`).\n\n## Authentication\n\n`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.\n\nThe 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.\n\nThe public resource continues to advertise only the compatible `api` scope. Authenticated requests use:\n\n```txt\nAuthorization: Bearer \n```\n\nBearer syntax is not authentication. Access is scoped to the exact canonical resource `https://mcp.spala.ai/mcp` with `api`. The public OAuth metadata, authorization, token, revocation, and registration endpoints are served from `mcp.spala.ai`. Dynamic registration accepts loopback HTTP callbacks, the exact hosted Claude and VS Code callbacks, and the existing validated native callback schemes; arbitrary web origins, wildcard hosts, callback queries, and callback fragments remain rejected. Authorization creates an encrypted request ticket and redirects to `dashboard.spala.ai/mcp/authorize`; the dashboard obtains `approvalProof` from its normal authenticated API and submits JSON `{ \"request\": \"...\", \"approvalProof\": \"...\" }` without `Authorization` to `/oauth/dashboard/approve`. The public service consumes that proof through its service-authenticated fixed platform API, and the local authorization code carries only the resulting one-time platform grant code. The platform issues opaque short access and rotating refresh credentials bound to the canonical resource. The public service encrypts the opaque platform access credential inside the public access token, unwraps it only for fixed typed platform operations, and never stores it in replay state. Upstream 5xx, network, timeout, and malformed-success failures return retryable `temporarily_unavailable` errors; exact approval, code-exchange, and refresh retries remain recoverable without allowing changed bindings. Invalid grants return `400`; invalid protected access returns a reliable `401` Bearer challenge, while anonymous `initialize`, `tools/list`, and the six public discovery tools remain usable even when a stale credential is presented. An invalid scope returns `403 insufficient_scope`, and OAuth rate limits return `429`. Credentials are never logged, placed in public URLs or manifests, or returned by MCP tools.\n\nSingle-binding ticket and authorization-code claims are stored as hash-only markers under `PUBLIC_OAUTH_REPLAY_STATE_PATH`; exact duplicates reuse the same result, changed replays are rejected, and request contents and platform grant codes are not written there. Refresh rotation and replay protection are atomic on the platform issuer. The service requires `0700` on an existing state directory, creates new state and expiration-bucket directories with `0700`, writes markers with `0600`, creates each claim with atomic exclusive file creation, syncs it before returning credentials, and removes expired buckets during later claims. Pre-provision a dedicated production path or volume below the filesystem root with that mode and ownership by the service account. The path must persist across restarts and deployments. Multiple workers must share a filesystem with atomic cross-process `O_EXCL` behavior and run as the same service account. Hosted configuration refuses to start without an explicit path or platform service secret, and replay-state initialization or runtime I/O failures fail closed instead of falling back to process memory. Local HTTP development defaults to the gitignored `.state/public-oauth-replay` directory when no path is supplied. Legacy encrypted public-MCP refresh credentials are not rotated; this migration can require one final interactive reauthentication.\n\n## Client install\n\n```bash\nnpx --yes @spala-ai/mcp-install init --client codex --yes --json\n```\n\nFor Codex this safely writes the user-scoped MCP configuration and a managed\nSpala routing skill, owns one native browser OAuth flow when first configured,\nthen requires a new or resumed session. Do not run a second login, manually\nopen its authorization URL, inspect client credential stores, or hand-roll MCP\nHTTP calls to bypass the reload boundary.\n\n## Project-handoff contract\n\nThe public MCP accepts an issued MCP OAuth token for `https://mcp.spala.ai/mcp` with scope `api`. Project listing and creation select a sole organization automatically; when multiple organizations are available, callers must provide one of the returned `organizationId` choices. Access checks remain enforced by Spala.\n\nThe upstream origin is configuration-only and never caller-controlled. Responses are parsed from documented fields; the service does not search arbitrary payloads for URLs or credentials.\n\nAfter public MCP OAuth, call `spala_start` as the protected first call. If it reports missing account data, ask the human one concise terminal question for exactly those fields and call `account_setup`; never invent placeholder names. Then ask for or confidently derive the real project name. Reuse the project recorded in the current workspace's `.spala/project.json` when it exists. Otherwise call `project_list`, and call `project_create` only when the intended project does not already exist. Then call `project_connect` with the project and one of `codex`, `roo`, `claude-code`, or `cursor`. Public MCP requests the existing dashboard project access URL, keeps its temporary project-entry credential server-side, and calls that exact project backend directly. The project backend performs its normal permission checks and enables MCP through the existing project settings API. Codex, Roo, and Cursor receive a short-lived one-time bootstrap-consumption URL. Claude Code first creates a local verifier, then calls `project_connect` again with its non-secret request ID and S256 challenge; the returned one-time claim can only be redeemed with that local verifier. No second browser OAuth is required.\n\n## Directory listing metadata\n\nThis repository includes `server.json` for MCP registries that accept source-backed remote server listings. The remote server URL is always:\n\n```txt\nhttps://mcp.spala.ai/mcp\n```\n\nThe repository does not include platform secrets, registry private keys, build output, `node_modules`, or local `.env` files.\n\n`package.json` versions the Node service implementation. `server.json` versions\nthe independently published MCP Registry listing. They are intentionally\nseparate release channels; update `server.json` only when publishing new\nregistry metadata.\n\n## Handoff\n\nPublic MCP accepts only the complete public HTTPS `mcpUrl` and `manifestUrl` returned by the authenticated project handoff. Before sending the reusable project-entry credential to a runtime builder-auth endpoint, it requires the MCP mount base to match the authenticated `projectUrl` origin and path exactly. This supports standalone deployments and custom domains without extra configuration. A distinct shared-runtime origin is fail-closed unless it appears exactly in `PUBLIC_MCP_TRUSTED_SHARED_RUNTIME_ORIGINS`, and configured shared runtimes must use the authoritative `//mcp` mount shape. Project MCP URLs may contain one canonical `scope` query composed only of `builder`, `project`, and `data`; arbitrary queries, credentials, fragments, duplicate scopes, and noncanonical URLs are rejected. The exact accepted string, including `/mcp/` and scope query, is preserved.\n\nAgentic workspace binding currently supports four client identifiers: `codex`, `roo`, `claude-code`, and `cursor`. Other applications may connect to the public MCP through their own MCP configuration, but `project_connect` does not return an executable project-binding plan for them. Without `client`, install-capable tools return `client_selection_required` and no executable plan.\n\nSuccessful Codex, Roo, and Cursor connections return a protected-bootstrap argv. The Codex shape is:\n\n```txt\nnpx --yes @spala-ai/mcp-install project bind --project-id --project-url --url --name --client codex --install-scope workspace --bootstrap-stdin --exact-url --yes --json\n```\n\nRun the argv immediately as a direct process from the intended project root with `tty:true` and `shell:false`. Wait for the process tool to report a running process, then use the process stdin tool to send `bootstrap.consumeUrl` plus a newline. Never interpolate the capability into shell text or process arguments. The capability is short-lived and one-time. The installer consumes it and configures a local credential proxy, then creates or updates `.spala/project.json`. Do not run native or manual project OAuth for this agentic flow; manual UI OAuth is unrelated. Never install a project MCP globally. The handoff, top-level response, install plan, and bootstrap exchange use the same authorized scoped MCP endpoint; subset scopes are never widened. The remote `manifestUrl` is informational and must not be fetched or passed to the installer. Follow the installer JSON reload instruction for the selected client.\n\nClaude Code uses two generated commands without `--bootstrap-stdin`. The first command creates a verifier in the user's protected credential store and returns only a non-secret request ID and S256 challenge:\n\n```txt\nnpx --yes @spala-ai/mcp-install project prepare --project-id --project-url --url --name --client claude-code --install-scope workspace --exact-url --yes --json\n```\n\nCall `project_connect` again with those two non-secret values. Run the returned `project bind` argv immediately; it contains the one-time claim and request ID, but never the verifier. The installer redeems the claim, stores the project credential outside the workspace, and configures the project-scoped local proxy. Reload Claude Code and call `spala_start` on the new project MCP. Do not start native project OAuth for this flow.\n\nAfter the authenticated contract returns an exact project MCP URL, the agent should connect to that project MCP and call:\n\n```txt\nspala_start\nmcp_get_skill({ \"name\": \"spala-developer\" })\nproject_get_builder_context\n```\n","changelogMarkdown","videoKey","requiredSecretsJson","[{\"name\":\"ACCEPT\",\"scope\":\"per-user\",\"header\":\"Accept\"}]","publishedAt","priceCents","trialDays","iconType","image","upstream",{"_108":109,"_110":-5,"_111":112,"_113":114,"_115":116,"_117":118},"requiredSecrets",[101],"tags",[],"assets",[],"stats",{"_99":59,"_100":59},"ratingAvg","reviewCount",{"_102":103,"_104":105,"_106":107},"name","ACCEPT","scope","per-user","header","Accept","topics",[],"license","language","TypeScript","registryName","ai.spala/public-mcp","homepage","https://spala.ai/mcp-profile/","packages",[],"ENV",{"_121":122,"_123":124,"_125":126},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]