Spala Public MCP
Descoberta, handoff OAuth e roteamento MCP de projetos para projetos backend Spala.
Documentação
Use o Spala Public MCP para descoberta, configuração de conta, transferência de projeto e o contrato operacional do Project MCP.
Spala Public MCP
O Spala Public MCP é o ponto de entrada do agente para a Spala:
Use este endpoint primeiro quando um agente de IA de codificação precisar entender ou trabalhar com a Spala, inclusive a partir de uma pasta de aplicativo completamente vazia. Não aguarde arquivos de frontend nem peça ao usuário para criar um projeto de dashboard. Ele não é o backend do projeto em si. Ele ajuda o agente a descobrir a Spala, autenticar, concluir a configuração de conta pendente, escolher ou criar um projeto e conectar o MCP do projeto correto.
Comando de inicialização do agente
Execute a partir do workspace do aplicativo do usuário, substituindo <client> por codex, claude-code, gemini ou outro cliente compatível:
pnpm dlx @spala-ai/mcp-install init --client <client> --yes --json
O agente deve executar os comandos de configuração retornados pelo instalador e, em seguida, verificar a instalação:
pnpm dlx @spala-ai/mcp-install status --json
Se o cliente ativo não conseguir carregar a quente o Public MCP recém-instalado, peça ao usuário para reiniciar ou retomar a mesma sessão do agente uma vez. Não peça ao usuário para criar ou selecionar um projeto no dashboard. Após a reinicialização, chame spala_start como a primeira ferramenta MCP protegida.
O login ou cadastro no navegador é a única ação esperada no navegador. Após a autenticação, o agente chama spala_start antes de account_status, ferramentas de projeto ou ferramentas de onboarding de compatibilidade e segue sua única nextAction. Para uma conta nova, essa ação solicita exatamente os campos de perfil/empresa ausentes e account_setup; após a transição de estado, chame spala_start novamente somente quando a ação retornada indicar que deve fazê-lo. Reutilize automaticamente apenas uma vinculação válida de local.spala/project.json. Caso contrário, apresente os projetos existentes para seleção do usuário ou peça um nome real de novo projeto e, em seguida, conecte e verifique o Project MCP exclusivo do workspace. Não envie o usuário para o onboarding do dashboard, não use placeholders, não aguarde arquivos de aplicativo nem crie um backend local separado.
Para Codex, o instalador público gerencia um único fluxo OAuth no navegador. Não inicie outro login nem abra manualmente uma segunda solicitação de autorização enquanto ela estiver pendente. Nunca leia credenciais de cliente, tokens ou armazenamento do navegador, e nunca crie chamadas de transporte manualmente para contornar um recarregamento de cliente necessário.
Nunca faça isso
Não adivinhe URLs do Project MCP. Não use https://api.spala.ai/{{project}}/mcp. Não configure o servidor de autorização OAuth como URL do servidor MCP. Não faça mutações de backend no Public MCP. O Public MCP descobre e transfere; o Project MCP constrói.
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 |
A URL do Project MCP é resolvida em tempo de execução a partir dos dados autenticados do projeto Spala. Ela não é derivada de um padrão de caminho fixo.
Checklist das primeiras chamadas
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.
O que o Public MCP pode fazer
Ferramentas 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 |
Boas consultas de docs_search são curtas e focadas:
oauth project handoff
create project and connect workspace MCP
codex setup
cursor project mcp
Ferramentas de transferência 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 |
Limite de autenticação
As ferramentas públicas de descoberta podem ser chamadas antes da autenticação da conta quando for necessário mais detalhe de compatibilidade. Após o OAuth, spala_start é a primeira chamada de ferramenta protegida. As ferramentas de projeto exigem a sessão OAuth da Spala do cliente MCP. O instalador e o cliente MCP gerenciam essas credenciais; usuários e agentes não devem copiar tokens para arquivos de projeto.
Metadados OAuth
A Spala publica a descoberta raiz do MCP em:
https://spala.ai/.well-known/mcp.json
A Spala publica os metadados OAuth do MCP em:
https://mcp.spala.ai/.well-known/oauth-protected-resource
https://mcp.spala.ai/.well-known/oauth-authorization-server
O servidor de autorização é descoberto a partir dos metadados OAuth. Não configure manualmente o servidor de autorização como URL do servidor MCP.
Os endpoints OAuth são:
| 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 |
Os grants suportados incluem authorization code e device code. O PKCE usa S256. A inicialização autenticada do Public MCP e a transferência usam o escopo api. O endpoint de token usa autenticação de cliente público (none) para o fluxo OAuth do MCP.
O ponto de entrada de login e cadastro no navegador é:
https://dashboard.spala.ai/signup
Fluxo correto do 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 o Public MCP
Execute pnpm dlx @spala-ai/mcp-install init --client <client> --yes --json, execute os comandos de configuração retornados e, em seguida, execute pnpm dlx @spala-ai/mcp-install status --json.
Recarregue somente quando necessário
Se o cliente atual não conseguir carregar a quente o Public MCP, peça ao usuário para reiniciar ou retomar a mesma sessão uma vez. Após a reinicialização, continue automaticamente; não envie o usuário para criar um projeto manualmente.
Autentique quando o acesso ao projeto for necessário
Conclua o único login ou cadastro no navegador da Spala aberto pelo instalador ou pelo cliente MCP. As credenciais permanecem gerenciadas pelo cliente; nunca inicie uma segunda autorização pendente.
Comece com a chamada protegida
Chame spala_start antes de qualquer outra ferramenta MCP protegida. Siga apenas sua única nextAction e chame-a novamente somente quando essa ação solicitar explicitamente após uma transição de estado.
Resolva e conecte o Project MCP
Se solicitado, pergunte uma vez pelos campos de conta ausentes e chame account_setup. Reutilize automaticamente apenas uma vinculação local válida; caso contrário, deixe o usuário selecionar um projeto existente ou nomear um novo e, em seguida, chame project_connect com um cliente compatível.
Alterne para o Project MCP
Execute o plano de vinculação exclusivo do workspace retornado, verifique a conexão e chame spala_start do Project MCP. As alterações de backend acontecem no Project MCP, não no Public MCP.
Padrão de endpoint errado
Não presuma https://api.spala.ai/{project}/mcp. Não escolha uma URL de Project MCP com base em formato ou padrão. Use apenas o mcpUrl exato retornado pela Spala após a autenticação e a seleção do projeto.
Notas para clientes MCP brutos
A maioria dos usuários deve usar um cliente com suporte a MCP, como Codex, Claude Code, Cursor, VS Code ou outro cliente que lide com os detalhes de transporte. Se você estiver implementando um cliente diretamente, use o protocolo MCP streamable HTTP em vez de chamar nomes de ferramentas como métodos JSON-RPC de nível superior.
O endpoint do Public MCP espera solicitações POST. Solicitações GET brutas para /mcp não fazem parte do protocolo MCP.
Cabeçalhos necessários:
Content-Type: application/json
Accept: application/json, text/event-stream
Após o OAuth, a primeira ferramenta protegida é chamada por meio de MCP tools/call:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "spala_start",
"arguments": {}
}
}
Use tools/list para descobrir as ferramentas disponíveis antes de tools/call. As ferramentas autenticadas exigem o mesmo transporte MCP e as credenciais OAuth gerenciadas pelo cliente MCP.
Formato bruto de solicitação para copiar e colar:
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": {}
}
}'
Clientes com suporte a MCP geralmente lidam com a configuração da sessão, a análise do stream e os cabeçalhos de autorização para você. Use HTTP bruto somente ao implementar ou depurar um cliente.
Falhas de autenticação
Se uma ferramenta de projeto retornar um erro de autenticação ou autorização:
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.
Erros de autenticação não são motivo para chamar https://api.spala.ai/{{project}}/mcp ou qualquer URL de Project MCP adivinhada.
Tokens bearer ausentes, inválidos ou expirados devem retornar 401 com um cabeçalho WWW-Authenticate apontando para os metadados de recurso protegido do MCP OAuth. Os clientes devem usar esse desafio para reiniciar ou atualizar o fluxo OAuth da plataforma Spala.
Transcrição bruta do MCP
Esta transcrição é para implementadores de clientes MCP. A maioria dos usuários deve deixar Codex, Claude Code, Cursor, VS Code ou outro cliente MCP lidar com essas chamadas de protocolo.
Busque os metadados OAuth:
GET https://mcp.spala.ai/.well-known/oauth-protected-resource
GET https://mcp.spala.ai/.well-known/oauth-authorization-server
Inicialize a sessão MCP:
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {
"name": "example-client",
"version": "1.0.0"
}
}
}
Liste as ferramentas:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}
Após o OAuth, chame a ferramenta de inicialização 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.
Conecte o projeto escolhido:
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "project_connect",
"arguments": {
"projectId": "PROJECT_ID_FROM_SPALA_START",
"client": "codex"
}
}
}
Leia o contexto seguro do projeto antes da transferência:
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "project_get_public_context",
"arguments": {
"projectId": "PROJECT_ID_FROM_SPALA_START"
}
}
}
A resposta de project_connect contém um plano de vinculação exato exclusivo do workspace e um valor de bootstrap único para o instalador local. Execute esse plano exatamente por meio do fluxo de cliente compatível, mantenha o valor de bootstrap fora de texto e argumentos de shell e não construa uma URL de Project MCP a partir de slug, host, URL base da API ou caminho adivinhado.
Contrato operacional do Project MCP
O Project MCP é a superfície de construção com escopo de projeto. O Public MCP ajuda o agente a descobrir a Spala, autenticar e resolver o projeto correto. O Project MCP é onde o agente trabalha em um backend.
Um agente deve usar este contrato operacional após a transferência:
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.
As categorias esperadas de ferramentas do Project MCP incluem:
| 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 |
A documentação pública descreve o contrato e o fluxo de trabalho, não dados privados do projeto. Os nomes exatos das ferramentas e esquemas do projeto são descobertos no Project MCP selecionado em tempo de execução.
Manifesto de instalação
O manifesto público de instalação é:
https://mcp.spala.ai/mcp/install-manifest
Use-o para comandos atuais, transporte, notas OAuth e a regra de resolução do Project MCP. A regra é sempre usar o mcpUrl explícito retornado pela 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