Spala Public MCP
Descubrimiento, transferencia OAuth y enrutamiento MCP de proyectos para proyectos backend de Spala.
Documentación
Usa el Spala Public MCP 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:
Usa este endpoint primero cuando un agente de codificación de IA necesite entender o trabajar con Spala, incluso desde una carpeta de aplicación completamente vacía. No esperes archivos de frontend ni pidas al usuario que cree un proyecto en el 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
Ejecuta 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 Public MCP recién instalado, pide al usuario reiniciar o reanudar la misma sesión del agente una vez. No pidas al usuario crear o seleccionar un proyecto en el dashboard. Después del reinicio, continúa con account_status y la transferencia de proyecto a continuación.
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 account_status. Para una cuenta nueva, hace una pregunta de terminal concisa exactamente sobre los campos de perfil/empresa faltantes reportados y llama a account_setup; esa llamada crea el espacio de trabajo de cuenta faltante. El nombre del proyecto es un paso siguiente separado: el agente lo pregunta o lo deriva con confianza, reutiliza o crea el proyecto, llama a project_connect exactamente una vez y ejecuta el plan de vinculación solo del espacio de trabajo. No envíes al usuario a la incorporación del dashboard, no uses nombres de marcador de posición, no esperes archivos de aplicación ni construyas un backend local separado.
Nunca hagas esto
No adivines las URL del MCP de proyecto. No uses https://api.spala.ai/{{project}}/mcp. No configures el servidor de autorización OAuth como la URL del servidor MCP. No hagas 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. 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.
Lo que el MCP público puede hacer
Herramientas públicas:
| 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 |
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 |
| --- | --- |
| 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 |
Límite de autenticación
Las herramientas de descubrimiento público se pueden llamar antes de la autenticación de cuenta. 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 configures 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. Los alcances del MCP público incluyen api, builder, ai, project y data. El endpoint de token usa autenticación de cliente público (ninguna) 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
-> 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
Instala el MCP público
Ejecuta pnpm dlx @spala-ai/mcp-install init --client <client> --yes --json, ejecuta sus comandos de configuración devueltos y luego ejecuta pnpm dlx @spala-ai/mcp-install status --json.
Recarga solo cuando sea necesario
Si el cliente actual no puede cargar en caliente el Public MCP, pide al usuario reiniciar o reanudar la misma sesión una vez. Después del reinicio, continúa automáticamente; no envíes al usuario a crear un proyecto manualmente.
Deja que el agente lea la incorporación
El agente debe llamar a spala_get_onboarding y luego a spala_get_tool_map. Los usuarios no necesitan aprender estas herramientas manualmente.
Autentícate cuando se necesite acceso al proyecto
Completa el inicio de sesión o registro en el navegador de Spala abierto por el cliente MCP. Las credenciales permanecen gestionadas por el cliente.
Resuelve y conecta el MCP de proyecto
Llama a account_status. Si es necesario, pregunta una vez por sus campos faltantes y llama a account_setup. Luego pregunta o deriva el nombre del proyecto, reutiliza o crea el proyecto y llama a project_connect exactamente una vez.
Cambia al MCP de proyecto
Ejecuta el plan de vinculación solo del espacio de trabajo devuelto. Los cambios de backend ocurren en el MCP de proyecto, no en el MCP público.
Patrón de endpoint incorrecto
No asumas https://api.spala.ai/{project}/mcp. No elijas una URL de MCP de proyecto por forma o patrón. Usa solo la mcpUrl exacta devuelta por Spala después de la autenticación y selección de proyecto.
Notas del cliente 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 implementas un cliente directamente, usa el protocolo HTTP transmisible de MCP 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
Conceptualmente, los documentos pueden decir "llama a spala_get_onboarding". En el cable, el cliente llama al método tools/call de MCP y pasa el nombre de la herramienta:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "spala_get_onboarding",
"arguments": {}
}
}
Usa tools/list para descubrir 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" \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "spala_get_onboarding",
"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 ti. Usa 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 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.
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 recursos protegidos 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 dejar que Codex, Claude Code, Cursor, VS Code u otro cliente MCP maneje estas llamadas de protocolo.
Obtén metadatos OAuth:
GET https://mcp.spala.ai/.well-known/oauth-protected-resource
GET https://mcp.spala.ai/.well-known/oauth-authorization-server
Inicializa 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"
}
}
}
Lista de herramientas:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}
Llama a la incorporación:
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "spala_get_onboarding",
"arguments": {}
}
}
Llama al mapa de herramientas:
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "spala_get_tool_map",
"arguments": {}
}
}
Después de la aprobación OAuth, lista proyectos:
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "project_list",
"arguments": {}
}
}
Conecta el proyecto elegido:
{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "project_connect",
"arguments": {
"projectId": "PROJECT_ID_FROM_PROJECT_LIST"
}
}
}
Lee el contexto seguro del proyecto antes de la transferencia:
{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "project_get_public_context",
"arguments": {
"projectId": "PROJECT_ID_FROM_PROJECT_LIST"
}
}
}
La respuesta de project_connect contiene un plan de vinculación único, solo del espacio de trabajo, para el MCP de proyecto. Llámalo una vez, ejecuta ese plan exactamente y no construyas una URL de MCP de proyecto a partir de un slug, host, URL base de API o ruta adivinada.
Contrato operativo del MCP de proyecto
El MCP de proyecto es la superficie de construcción específica del proyecto. El MCP público ayuda al agente a descubrir Spala, autenticarse y resolver el proyecto correcto. El MCP de proyecto es donde el agente trabaja en un backend.
Un agente debe usar este contrato operativo después de la transferencia:
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.
Las categorías esperadas de herramientas del MCP de proyecto 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 exactos de herramientas y esquemas 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
Úsalo 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