Spala Public MCP
Descubrimiento, transferencia OAuth y enrutamiento MCP de proyectos para proyectos backend de Spala.
Documentación
Use el MCP público de Spala para descubrimiento, configuración de cuenta, transferencia de proyectos y el contrato operativo del Project MCP.
Spala Public MCP
Spala Public MCP es el punto de entrada del agente para Spala:
Use este endpoint primero cuando un agente de IA de codificación necesite comprender o trabajar con Spala, incluso desde una carpeta de aplicación completamente vacía. No espere archivos de frontend ni pida al usuario que cree un proyecto de dashboard. No es el backend del proyecto en sí. Ayuda al agente a descubrir Spala, autenticarse, completar la configuración de cuenta faltante, elegir o crear un proyecto y conectar el MCP de proyecto correcto.
Comando de arranque del agente
Ejecute esto desde el espacio de trabajo de la aplicación del usuario, reemplazando <client> con codex, claude-code, gemini u otro cliente compatible:
pnpm dlx @spala-ai/mcp-install init --client <client> --yes --json
El agente debe ejecutar los comandos de configuración devueltos por el instalador y luego verificar la instalación:
pnpm dlx @spala-ai/mcp-install status --json
Si el cliente activo no puede cargar en caliente el MCP público recién instalado, pida al usuario que reinicie o reanude la misma sesión del agente una vez. No pida al usuario que cree o seleccione un proyecto en el dashboard. Después del reinicio, llame a spala_start como la primera herramienta MCP protegida.
El inicio de sesión o registro en el navegador es la única acción de navegador esperada. Después de la autenticación, el agente llama a spala_start antes de account_status, herramientas de proyecto o herramientas de incorporación de compatibilidad, y sigue su única nextAction. Para una cuenta nueva, esa acción solicita exactamente los campos de perfil/empresa faltantes y account_setup; después de la transición de estado, llame a spala_start nuevamente solo cuando la acción devuelta lo indique. Reutilice automáticamente solo un enlace válido de local.spala/project.json. De lo contrario, presente los proyectos existentes para que el usuario seleccione o solicite un nombre de proyecto nuevo real, luego conecte y verifique el MCP de proyecto exclusivo del espacio de trabajo. No envíe al usuario a la incorporación del dashboard, no use marcadores de posición, no espere archivos de aplicación ni cree un backend local independiente.
Para Codex, el instalador público gestiona un único flujo OAuth de navegador. No inicie otro inicio de sesión ni abra manualmente una segunda solicitud de autorización mientras esté pendiente. Nunca lea credenciales de cliente, tokens o almacenamiento del navegador, y nunca cree llamadas de transporte manuales para omitir una recarga de cliente requerida.
Nunca haga esto
No adivine las URL del MCP de proyecto. No use https://api.spala.ai/{{project}}/mcp. No configure el servidor de autorización OAuth como la URL del servidor MCP. No realice mutaciones de backend en el MCP público. El MCP público descubre y transfiere; el MCP de proyecto construye.
MCP público vs MCP de proyecto
| 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 |
La URL del MCP de proyecto se resuelve en tiempo de ejecución a partir de los datos autenticados del proyecto Spala. No se deriva de un patrón de ruta fijo.
Lista de verificación de primeras llamadas
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.
Qué puede hacer el MCP público
Herramientas públicas:
| 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 |
Las buenas consultas de docs_search son cortas y enfocadas:
oauth project handoff
create project and connect workspace MCP
codex setup
cursor project mcp
Herramientas de transferencia autenticadas:
| 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 |
Límite de autenticación
Las herramientas de descubrimiento público se pueden llamar antes de la autenticación de cuenta cuando se necesita más detalle de compatibilidad. Después de OAuth, spala_start es la primera llamada de herramienta protegida. Las herramientas de proyecto requieren la sesión OAuth de Spala del cliente MCP. El instalador y el cliente MCP gestionan estas credenciales; los usuarios y agentes no deben copiar tokens en archivos de proyecto.
Metadatos OAuth
Spala publica el descubrimiento raíz de MCP en:
https://spala.ai/.well-known/mcp.json
Spala publica los metadatos OAuth de MCP en:
https://mcp.spala.ai/.well-known/oauth-protected-resource
https://mcp.spala.ai/.well-known/oauth-authorization-server
El servidor de autorización se descubre desde los metadatos OAuth. No configure manualmente el servidor de autorización como la URL del servidor MCP.
Los endpoints OAuth son:
| 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 |
Los flujos admitidos incluyen código de autorización y código de dispositivo. PKCE usa S256. El inicio autenticado del MCP público y la transferencia usan el alcance api. El endpoint de token usa autenticación de cliente público (none) para el flujo OAuth de MCP.
El punto de entrada de inicio de sesión y registro en el navegador es:
https://dashboard.spala.ai/signup
Flujo correcto del agente
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
Instale el MCP público
Ejecute pnpm dlx @spala-ai/mcp-install init --client <client> --yes --json, ejecute los comandos de configuración devueltos y luego ejecute pnpm dlx @spala-ai/mcp-install status --json.
Recargue solo cuando sea necesario
Si el cliente actual no puede cargar en caliente el MCP público, pida al usuario que reinicie o reanude la misma sesión una vez. Después del reinicio, continúe automáticamente; no envíe al usuario a crear un proyecto manualmente.
Autentíquese cuando se necesite acceso al proyecto
Complete el único inicio de sesión o registro en el navegador de Spala abierto por el instalador o el cliente MCP. Las credenciales permanecen gestionadas por el cliente; nunca inicie una segunda autorización pendiente.
Comience con la llamada protegida
Llame a spala_start antes que cualquier otra herramienta MCP protegida. Siga solo su única nextAction y llámela nuevamente solo cuando esa acción lo solicite explícitamente después de una transición de estado.
Resuelva y conecte el MCP de proyecto
Si se solicita, pregunte una vez por los campos de cuenta faltantes y llame a account_setup. Reutilice automáticamente solo un enlace local válido; de lo contrario, permita que el usuario seleccione un proyecto existente o nombre uno nuevo, luego llame a project_connect con un cliente compatible.
Cambie al MCP de proyecto
Ejecute el plan de enlace exclusivo del espacio de trabajo devuelto, verifique la conexión y llame a spala_start del MCP de proyecto. Los cambios de backend ocurren en el MCP de proyecto, no en el MCP público.
Patrón de endpoint incorrecto
No asuma https://api.spala.ai/{project}/mcp. No elija una URL de MCP de proyecto por forma o patrón. Use solo la mcpUrl exacta devuelta por Spala después de la autenticación y selección de proyecto.
Notas para clientes MCP sin procesar
La mayoría de los usuarios deberían usar un cliente compatible con MCP como Codex, Claude Code, Cursor, VS Code u otro cliente que maneje los detalles de transporte. Si está implementando un cliente directamente, use el protocolo MCP streamable HTTP en lugar de llamar nombres de herramientas como métodos JSON-RPC de nivel superior.
El endpoint del MCP público espera solicitudes POST. Las solicitudes GET sin procesar a /mcp no son el protocolo MCP.
Encabezados requeridos:
Content-Type: application/json
Accept: application/json, text/event-stream
Después de OAuth, la primera herramienta protegida se llama a través de MCP tools/call:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "spala_start",
"arguments": {}
}
}
Use tools/list para descubrir las herramientas disponibles antes de tools/call. Las herramientas autenticadas requieren el mismo transporte MCP y las credenciales OAuth gestionadas por el cliente MCP.
Forma de solicitud sin procesar para copiar y pegar:
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": {}
}
}'
Los clientes compatibles con MCP generalmente manejan la configuración de sesión, el análisis de flujo y los encabezados de autorización por usted. Use HTTP sin procesar solo al implementar o depurar un cliente.
Fallos de autenticación
Si una herramienta de proyecto devuelve un error de autenticación o autorización:
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.
Los errores de autenticación no son motivo para llamar a https://api.spala.ai/{{project}}/mcp ni a ninguna URL de MCP de proyecto adivinada.
Los tokens de portador faltantes, inválidos o caducados deben devolver 401 con un encabezado WWW-Authenticate que apunte a los metadatos de recurso protegido OAuth de MCP. Los clientes deben usar ese desafío para reiniciar o actualizar el flujo OAuth de la plataforma Spala.
Transcripción MCP sin procesar
Esta transcripción es para implementadores de clientes MCP. La mayoría de los usuarios deberían permitir que Codex, Claude Code, Cursor, VS Code u otro cliente MCP maneje estas llamadas de protocolo.
Obtener metadatos OAuth:
GET https://mcp.spala.ai/.well-known/oauth-protected-resource
GET https://mcp.spala.ai/.well-known/oauth-authorization-server
Inicializar la sesión MCP:
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {
"name": "example-client",
"version": "1.0.0"
}
}
}
Listar herramientas:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}
Después de OAuth, llame a la herramienta de inicio protegida:
{
"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.
Conectar el proyecto elegido:
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "project_connect",
"arguments": {
"projectId": "PROJECT_ID_FROM_SPALA_START",
"client": "codex"
}
}
}
Leer el contexto seguro del proyecto antes de la transferencia:
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "project_get_public_context",
"arguments": {
"projectId": "PROJECT_ID_FROM_SPALA_START"
}
}
}
La respuesta de project_connect contiene un plan de enlace exclusivo del espacio de trabajo exacto y un valor de arranque único para el instalador local. Ejecute ese plan exactamente a través del flujo de cliente compatible, mantenga el valor de arranque fuera del texto y los argumentos del shell, y no construya una URL de MCP de proyecto a partir de un slug, host, URL base de API o ruta adivinada.
Contrato operativo del Project MCP
El Project MCP es la superficie de construcción a nivel de proyecto. El MCP público ayuda al agente a descubrir Spala, autenticarse y resolver el proyecto correcto. El Project MCP es donde el agente trabaja en un backend.
Un agente debe usar este contrato operativo después de la transferencia:
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.
Las categorías esperadas de herramientas del Project MCP incluyen:
| 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 |
Los documentos públicos describen el contrato y el flujo de trabajo, no datos privados del proyecto. Los nombres y esquemas exactos de las herramientas del proyecto se descubren desde el MCP de proyecto seleccionado en tiempo de ejecución.
Manifiesto de instalación
El manifiesto de instalación público es:
https://mcp.spala.ai/mcp/install-manifest
Úselo para comandos actuales, transporte, notas OAuth y la regla de resolución del MCP de proyecto. La regla es siempre usar la mcpUrl explícita devuelta por 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