Spala Public MCP
Discovery, OAuth handoff, and project MCP routing for Spala backend projects.
Documentation
Use the public Spala MCP for discovery, account setup, project handoff, and the Project MCP operating contract.
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.
Agent bootstrap command
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, call spala_start as the protected first MCP tool.
Browser sign-in or signup is the only expected browser action. After authentication, the agent calls spala_start before account_status, project tools, or compatibility onboarding tools and follows its single nextAction. For a new account, that action requests exactly the missing profile/company fields and account_setup; after the state transition, call spala_start again only when the returned action says to do so. Automatically reuse only a valid local.spala/project.json binding. Otherwise present existing projects for user selection or ask for a real new project name, then connect and verify the workspace-only project MCP. Do not send the user to dashboard onboarding, use placeholders, wait for application files, or build a separate local-only backend.
For Codex, the public installer owns one browser OAuth flow. Do not start another login or manually open a second authorization request while it is pending. Never read client credentials, tokens, or browser storage, and never hand-roll transport calls to bypass a required client reload.
Never do this
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.
Public MCP vs Project MCP
| 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.
First calls checklist
1. Reuse a valid configured .spala/project.json binding when one exists; otherwise install or use Public MCP.
2. Run installer status and complete the single browser sign-in or signup flow when requested.
3. Reload the client only when its returned setup plan requires it.
4. Call spala_start as the protected first MCP tool.
5. Follow exactly its single nextAction. If setup is required, ask once for the requested real values and call account_setup.
6. Call spala_start again only when the prior action explicitly requests it after a state transition.
7. Automatically reuse only a valid local binding. Otherwise present existing projects or ask for a new project name, then call project_connect with a supported client.
8. Execute the exact workspace-only bind plan, verify the project MCP, and call that MCP's spala_start.
What the public MCP can do
Public tools:
| Tool | Purpose |
| --- | --- |
| spala_help | Explain what Spala is and how agents should start |
| spala_get_onboarding | Optional compatibility guidance when broader onboarding detail is needed |
| spala_get_tool_map | Optional compatibility map for public MCP versus project MCP routing |
| 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
Authenticated handoff tools:
| Tool | Purpose |
| --- | --- |
| spala_start | Protected first call after OAuth; returns the one next account, organization, project, billing, or handoff action |
| account_status | Compatibility status detail; do not call it before spala_start |
| account_setup | Fill missing profile data and create the first company/workspace after one concise user question |
| organization_create | Create an additional organization when the startup action requires it |
| project_list | List projects available to the authenticated Spala user |
| project_connect | Prepare the chosen project's MCP and return an exact workspace-only 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 |
Authentication boundary
Public discovery tools can be called before account authentication when broader compatibility detail is needed. After OAuth, spala_start is the protected first tool call. 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.
OAuth metadata
Spala publishes root MCP discovery at:
https://spala.ai/.well-known/mcp.json
Spala publishes MCP OAuth metadata at:
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.
OAuth endpoints are:
| 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 authenticated startup and handoff use the api scope. The token endpoint uses public-client auth (none) for the MCP OAuth flow.
The browser sign-in and signup entrypoint is:
https://dashboard.spala.ai/signup
Correct agent flow
AI client
-> run @spala-ai/mcp-install init and returned setup steps
-> run @spala-ai/mcp-install status
-> Public MCP: https://mcp.spala.ai/mcp
-> browser sign-in/signup when required
-> spala_start as the protected first MCP tool
-> account_setup when required, using real user-confirmed account data
-> spala_start again only when its prior nextAction requests it
-> reuse a valid local binding, or ask the user to select a project or name a new one
-> project_connect with a supported client when no binding was reused
-> execute returned workspace-only bind plan
-> connected project MCP
-> spala_start, then its mandatory inspections
-> preview, validate, apply, publish when requested, review
Install the public MCP
Run pnpm dlx @spala-ai/mcp-install init --client <client> --yes --json, execute its returned setup commands, then run pnpm dlx @spala-ai/mcp-install status --json.
Reload only when required
If the current client cannot hot-load Public MCP, ask the user to restart or resume the same session once. After restart, continue automatically; do not send the user to create a project manually.
Authenticate when project access is needed
Complete the single Spala browser sign-in or signup opened by the installer or MCP client. Credentials stay client-managed; never start a second pending authorization.
Start with the protected call
Call spala_start before any other protected MCP tool. Follow only its single nextAction, and call it again only when that action explicitly requests it after a state transition.
Resolve and connect the project MCP
If requested, ask once for missing account fields and call account_setup. Automatically reuse only a valid local binding; otherwise let the user select an existing project or name a new one, then call project_connect with a supported client.
Switch to the project MCP
Execute the returned workspace-only bind plan, verify the connection, and call the project MCP's spala_start. Backend changes happen on the project MCP, not on the public MCP.
Wrong endpoint pattern
Do not assume https://api.spala.ai/{project}/mcp. Do not choose a project MCP URL from a shape or pattern. Use only the exact mcpUrl returned by Spala after authentication and project selection.
Raw MCP Client Notes
Most users should use an MCP-aware client such as Codex, Claude Code, Cursor, VS Code, or another client that handles transport details. If you are implementing a client directly, use the MCP streamable HTTP protocol rather than calling tool names as top-level JSON-RPC methods.
The public MCP endpoint expects POST requests. Raw GET requests to /mcp are not the MCP protocol.
Required headers:
Content-Type: application/json
Accept: application/json, text/event-stream
After OAuth, the protected first tool is called through MCP tools/call:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "spala_start",
"arguments": {}
}
}
Use tools/list to discover available tools before tools/call. Authenticated tools require the same MCP transport and the OAuth credentials managed by the MCP client.
Copy-paste raw request shape:
curl -X POST "https://mcp.spala.ai/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer ACCESS_TOKEN" \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "spala_start",
"arguments": {}
}
}'
MCP-aware clients usually handle session setup, stream parsing, and authorization headers for you. Use raw HTTP only when implementing or debugging a client.
Auth failures
If a project tool returns an authentication or authorization error:
1. Read the MCP OAuth metadata again.
2. Start exactly one client OAuth/browser approval flow if no token is available.
3. Retry spala_start after the MCP client reports authentication complete.
4. If the token is expired, refresh or repeat OAuth according to the authorization server metadata without creating concurrent login requests.
5. If the user lacks project access, ask the user to grant access in the Spala dashboard instead of guessing another project URL.
Auth errors are not a reason to call https://api.spala.ai/{{project}}/mcp or any guessed project MCP URL.
Missing, invalid, or expired bearer tokens should return 401 with a WWW-Authenticate header pointing to the MCP OAuth protected-resource metadata. Clients should use that challenge to restart or refresh the Spala platform OAuth flow.
Raw MCP transcript
This transcript is for MCP client implementers. Most users should let Codex, Claude Code, Cursor, VS Code, or another MCP client handle these protocol calls.
Fetch OAuth metadata:
GET https://mcp.spala.ai/.well-known/oauth-protected-resource
GET https://mcp.spala.ai/.well-known/oauth-authorization-server
Initialize the MCP session:
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {
"name": "example-client",
"version": "1.0.0"
}
}
}
List tools:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}
After OAuth, call the protected startup tool:
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "spala_start",
"arguments": {}
}
}
Follow the single nextAction in the response. If it requests account_setup,
complete that action and call spala_start again only when instructed. The
startup response supplies project choices when the account is ready.
Connect the chosen project:
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "project_connect",
"arguments": {
"projectId": "PROJECT_ID_FROM_SPALA_START",
"client": "codex"
}
}
}
Read safe project context before handoff:
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "project_get_public_context",
"arguments": {
"projectId": "PROJECT_ID_FROM_SPALA_START"
}
}
}
The project_connect response contains an exact workspace-only bind plan and a one-time bootstrap value for the local installer. Execute that plan exactly through the supported client flow, keep the bootstrap value out of shell text and arguments, and do not construct a project MCP URL from a slug, host, API base URL, or guessed path.
Project MCP operating contract
Project MCP is the project-scoped build surface. Public MCP helps the agent discover Spala, authenticate, and resolve the correct project. Project MCP is where the agent works on one backend.
An agent should use this operating contract after handoff:
1. Call project MCP spala_start first.
2. Run every mandatory inspection returned by spala_start.
3. Load only the focused project skill when needed; legacy onboarding and tool-map calls are optional compatibility tools.
4. Draft Step Script locally, convert it with safe repairs enabled, and preview it.
5. Fix blockers or repair feedback and repeat preview until clean.
6. Apply only after a clean preview, then validate the project.
7. Publish only when requested or required by the implementation workflow.
8. Apply deterministic repairs only when publish returns the exact repair set, then retry publish.
9. Run project test review and treat missing environment variables, warnings, and repair feedback as blockers for the next revision.
10. Use snapshots, pull requests, revert-to-published, or rollback surfaces when recovery is needed.
Expected project-MCP tool categories include:
| Category | Purpose |
| --- | --- |
| Context | Read builder contract, auth rules, project state, graph, resources, and environment requirements |
| Preview | Preview generated or edited models, endpoints, functions, tasks, triggers, agents, and channels |
| Apply | Save scoped backend resource changes after preview and validation |
| Validate | Check project consistency, auth safety, references, missing configuration, and publish readiness |
| Publish | Promote the project draft to the live API when appropriate |
| Review | Inspect publish/test results, warnings, repair feedback, logs, and generated docs |
| Recovery | Use snapshots, pull requests, version history, rollback, or revert-to-published when a change needs to be undone |
The public docs describe the contract and workflow, not private project data. The exact project tool names and schemas are discovered from the selected project MCP at runtime.
Install manifest
The public install manifest is:
https://mcp.spala.ai/mcp/install-manifest
Use it for current commands, transport, OAuth notes, and the project MCP resolution rule. The rule is always to use the explicit mcpUrl returned by Spala.
Codex Setup
/agents/codex
Add Spala MCP to Codex
Claude Setup
/agents/claude
Add Spala MCP to Claude Code
Cursor Setup
/agents/cursor
Configure Cursor with Spala MCP
Public Agent Skills
/agents/skills
Public skill files for evaluation and safe workflow
Quick Start
/getting-started/quickstart
Build a backend from the dashboard