Spala Public MCP

Spala Public MCP is the agent entrypoint for Spala:

Use this endpoint first when an AI coding agent needs to understand or work with Spala, including from a completely empty app folder. Do not wait for frontend files or ask the user to create a dashboard project. It is not the project backend itself. It helps the agent discover Spala, authenticate, complete missing account setup, choose or create a project, and connect the correct project MCP.

Run this from the user's app workspace, replacing <client> with codex, claude-code, gemini, or another supported client:

pnpm dlx @spala-ai/mcp-install init --client <client> --yes --json

The agent must execute the setup commands returned by the installer, then verify the installation:

pnpm dlx @spala-ai/mcp-install status --json

If the active client cannot hot-load the newly installed Public MCP, ask the user to restart or resume the same agent session once. Do not ask the user to create or select a project in the dashboard. After restart, continue with account_status and the project handoff below.

Browser sign-in or signup is the only expected browser action. After authentication, the agent calls account_status. For a new account, it asks one concise terminal question for exactly the reported missing profile/company fields and calls account_setup; that call creates the missing account workspace. Project name is a separate next step: the agent asks for or confidently derives it, reuses or creates the project, calls project_connect exactly once, and executes the workspace-only bind plan. Do not send the user to dashboard onboarding, use placeholder names, wait for application files, or build a separate local-only backend.

Do not guess project MCP URLs. Do not use[https://api.spala.ai/{{project}}/mcp. Do not configure the OAuth authorization server as the MCP server URL. Do not make backend mutations on public MCP. Public MCP discovers and hands off; project MCP builds.

| Surface | URL | Purpose | Can mutate backend? | | --- | --- | --- | --- | | Public MCP | https://mcp.spala.ai/mcp | Discover Spala, read onboarding, search docs, expose OAuth metadata, list/select projects after auth | No | | Project MCP | Connected by project_connect after auth and project choice | Inspect one project, preview changes, validate, apply, publish when requested, review behavior | Yes, after project auth and validation |

The project MCP URL is resolved at runtime from authenticated Spala project data. It is not derived from a fixed path pattern.

1. Run the installer init command and execute its returned setup steps. 2. Run installer status. 3. Complete browser sign-in or signup when requested. 4. Call spala_get_onboarding, spala_get_tool_map, then account_status. 5. If setup is required, ask once for exactly missingFields and call account_setup with real values. 6. Ask for or derive the real project name; reuse .spala/project.json, list projects, or call project_create only when needed. 7. Call project_connect exactly once and execute its returned workspace-only bind plan. 8. Continue on the connected project MCP.

| Tool | Purpose | | --- | --- | | spala_help | Explain what Spala is and how agents should start | | spala_get_onboarding | First call for agents connected to the public MCP | | spala_get_tool_map | Machine-readable routing between public MCP and project MCP | | docs_search | Search agent-facing Spala docs when the agent needs more context | | template_list | Optional starter-pattern lookup for agents | | addon_list | Optional integration lookup for agents |

Good docs_search queries are short and focused:

oauth project handoff create project and connect workspace MCP codex setup cursor project mcp

| Tool | Purpose | | --- | --- | | account_status | Verify the authenticated Spala account before project work | | account_setup | Fill missing profile data and create the first company/workspace after one concise user question | | project_list | List projects available to the authenticated Spala user | | project_connect | Prepare the chosen project's MCP and return a one-time workspace bind plan | | project_get_mcp_manifest | Return the selected project's MCP install manifest shape | | project_get_public_context | Return safe project context for the selected project | | project_create | Create a project when no suitable existing project or local binding should be reused |

Public discovery tools can be called before account authentication. Project tools require the MCP client's Spala OAuth session. The installer and MCP client manage these credentials; users and agents should not copy tokens into project files.

https://mcp.spala.ai/.well-known/oauth-protected-resource https://mcp.spala.ai/.well-known/oauth-authorization-server

The authorization server is discovered from the OAuth metadata. Do not manually configure the authorization server as the MCP server URL.

| Endpoint | URL | | --- | --- | | Authorization | Discovered from /.well-known/oauth-authorization-server | | Token | Discovered from /.well-known/oauth-authorization-server | | Dynamic registration | Discovered from /.well-known/oauth-authorization-server | | Device authorization | Discovered from /.well-known/oauth-authorization-server |

Supported grants include authorization code and device code. PKCE uses S256. Public MCP scopes include api, builder, ai, project, and data. The token endpoint uses public-client auth (none) for the MCP OAuth flow.