Spala Public MCP

Spala Public MCP

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:

https://mcp.spala.ai/mcp

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 with codex, claude-code, gemini, or another supported client:

pnpm dlx @spala-ai/mcp-install init --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.

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. 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.

What the public MCP can do

Public tools:

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

Authenticated handoff tools:

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

Authentication boundary

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.

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 scopes include api, builder, ai, project, and data. 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 -> spala_get_onboarding -> spala_get_tool_map -> browser sign-in/signup when required -> account_status -> account_setup when required, using real user-confirmed account data -> ask for or derive the project name; reuse local binding, list projects, or create the intended project -> project_connect exactly once -> execute returned workspace-only bind plan -> connected project MCP -> inspect context on project MCP -> 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.

Let the agent read onboarding

The agent should call spala_get_onboarding, then spala_get_tool_map. Users do not need to learn these tools by hand.

Authenticate when project access is needed

Complete the Spala browser sign-in or signup opened by the MCP client. Credentials stay client-managed.

Resolve and connect the project MCP

Call account_status. If required, ask once for its missing fields and call account_setup. Then ask for or derive the project name, reuse or create the project, and call project_connect exactly once.

Switch to the project MCP

Execute the returned workspace-only bind plan. 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

Conceptually, docs may say "call spala_get_onboarding." On the wire, the client calls the MCP tools/call method and passes the tool name:

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "spala_get_onboarding", "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"
--data '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "spala_get_onboarding", "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 the client OAuth/browser approval flow if no token is available.
3. Retry the same tool after the MCP client reports authentication complete.
4. If the token is expired, refresh or repeat OAuth according to the authorization server metadata.
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": {} }

Call onboarding:

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "spala_get_onboarding", "arguments": {} } }

Call the tool map:

{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "spala_get_tool_map", "arguments": {} } }

After OAuth approval, list projects:

{ "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "project_list", "arguments": {} } }

Connect the chosen project:

{ "jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": { "name": "project_connect", "arguments": { "projectId": "PROJECT_ID_FROM_PROJECT_LIST" } } }

Read safe project context before handoff:

{ "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "project_get_public_context", "arguments": { "projectId": "PROJECT_ID_FROM_PROJECT_LIST" } } }

The project_connect response contains a one-time, workspace-only bind plan for the project MCP. Call it once, execute that plan exactly, 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. Authenticate through Spala platform OAuth when the client requires project access.
2. Read onboarding and the project tool map if the project MCP exposes them.
3. Inspect builder context and current project state before proposing changes.
4. Preview changes before applying them.
5. Validate the project before saving, applying, or publishing.
6. Apply only the scoped resources requested by the user.
7. Publish only when the user requested publish or the workflow explicitly requires it.
8. Run publish/test review after publish.
9. Treat repair feedback, missing environment variables, auth warnings, and validation errors 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