Spala Public MCP

Use the public Spala MCP for discovery, OAuth metadata, project lookup, and project MCP handoff.

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. It is not the project backend itself. It helps the agent discover Spala, authenticate, choose a project, and receive the correct project MCP URL.

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 | Returned by project_select or project manifest after auth | 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. Connect to https://mcp.spala.ai/mcp.
2. Call spala_get_onboarding.
3. Call spala_get_tool_map.
4. Use OAuth when project access is needed.
5. Call project_list, then project_select.
6. Continue on the exact project MCP URL returned by Spala.

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
project_create dry-run
codex setup
cursor project mcp

Authenticated handoff tools:

| Tool | Purpose |
| --- | --- |
| project_list | List projects available to the authenticated Spala user |
| project_select | Select a project and return its project MCP URL |
| 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 | Dry-run only in the current public MCP deployment; previews project creation and does not create a real project |

Authentication boundary

Public discovery tools can be called before project bearer auth. Some MCP clients may still require platform approval before installing or using the server. Project tools require Authorization: Bearer SPALA_PLATFORM_ACCESS_TOKEN.

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 dashboard entrypoint for browser approval is:

https://dashboard.spala.ai/signup

Correct agent flow

AI client
  -> Public MCP: https://mcp.spala.ai/mcp
  -> spala_get_onboarding
  -> spala_get_tool_map
  -> OAuth when project access is needed
  -> project_list
  -> project_select
  -> exact project MCP URL returned by Spala
  -> inspect context on project MCP
  -> preview, validate, apply, publish when requested, review

Add the public MCP

Configure the AI client with https://mcp.spala.ai/mcp.

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

Use the OAuth metadata advertised by the MCP server. The client should send Authorization: Bearer SPALA_PLATFORM_ACCESS_TOKEN for project tools.

Resolve the project MCP

Call project_list and project_select, or use the project MCP manifest returned by Spala.

Switch to the project MCP

Backend changes happen on the returned 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 plus Authorization: Bearer SPALA_PLATFORM_ACCESS_TOKEN.

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 with Authorization: Bearer SPALA_PLATFORM_ACCESS_TOKEN.
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": {}
  }
}

Select a project:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "project_select",
    "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_select or project_get_mcp_manifest response contains the project MCP URL or install manifest. Use that exact value. 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