Spala Public MCP
Descoberta, handoff OAuth e roteamento MCP de projetos para projetos backend Spala.
Documentação
Use o Spala MCP público para descoberta, configuração de conta, transferência de projeto e o contrato operacional do Project MCP.
Spala Public MCP
Spala Public MCP é o ponto de entrada do agente para o Spala:
Use este endpoint primeiro quando um agente de codificação de IA precisar entender ou trabalhar com o Spala, inclusive a partir de uma pasta de aplicativo completamente vazia. Não espere por arquivos de frontend nem peça ao usuário para criar um projeto no dashboard. Ele não é o backend do projeto em si. Ele ajuda o agente a descobrir o Spala, autenticar, concluir a configuração de conta ausente, escolher ou criar um projeto e conectar o project MCP correto.
Comando de inicialização do agente
Execute isto 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, continue com account_status e a transferência de projeto abaixo.
O login ou cadastro no navegador é a única ação esperada no navegador. Após a autenticação, o agente chama account_status. Para uma nova conta, ele faz uma pergunta concisa no terminal exatamente sobre os campos de perfil/empresa ausentes relatados e chama account_setup; essa chamada cria o workspace de conta ausente. O nome do projeto é uma etapa separada: o agente pergunta ou deriva com confiança, reutiliza ou cria o projeto, chama project_connect exatamente uma vez e executa o plano de bind somente do workspace. Não envie o usuário para a integração do dashboard, não use nomes de espaço reservado, não espere por arquivos de aplicativo nem crie um backend separado somente local.
Nunca faça isto
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 a URL do servidor MCP. Não faça mutações de backend no public MCP. O public MCP descobre e faz a transferência; 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.
Lista de verificação das primeiras chamadas
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.
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 | 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 |
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 |
| --- | --- |
| 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 |
Limite de autenticação
As ferramentas de descoberta públicas podem ser chamadas antes da autenticação da conta. As ferramentas de projeto exigem a sessão OAuth do 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
O Spala publica a descoberta raiz do MCP em:
https://spala.ai/.well-known/mcp.json
O 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 a 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. Os escopos do public MCP incluem api, builder, ai, project e data. 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
-> 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
Instalar 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.
Recarregar 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.
Deixe o agente ler a integração
O agente deve chamar spala_get_onboarding e depois spala_get_tool_map. Os usuários não precisam aprender essas ferramentas manualmente.
Autenticar quando o acesso ao projeto for necessário
Conclua o login ou cadastro no navegador do Spala aberto pelo cliente MCP. As credenciais permanecem gerenciadas pelo cliente.
Resolver e conectar o project MCP
Chame account_status. Se necessário, pergunte uma vez sobre os campos ausentes e chame account_setup. Em seguida, pergunte ou derive o nome do projeto, reutilize ou crie o projeto e chame project_connect exatamente uma vez.
Alternar para o project MCP
Execute o plano de bind somente do workspace retornado. As alterações de backend acontecem no project MCP, não no public MCP.
Padrão de endpoint incorreto
Não presuma https://api.spala.ai/{project}/mcp. Não escolha uma URL do project MCP a partir de uma forma ou padrão. Use apenas o mcpUrl exato retornado pelo Spala após a autenticação e a seleção do projeto.
Notas sobre clientes MCP brutos
A maioria dos usuários deve usar um cliente compatível com 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 HTTP transmissível do MCP 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 são o protocolo MCP.
Cabeçalhos necessários:
Content-Type: application/json
Accept: application/json, text/event-stream
Conceitualmente, a documentação pode dizer "chame spala_get_onboarding". Na prática, o cliente chama o método tools/call do MCP e passa o nome da ferramenta:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "spala_get_onboarding",
"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 de solicitação bruta para copiar e colar:
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": {}
}
}'
Clientes compatíveis com 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 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.
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 OAuth do MCP. 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 o Codex, Claude Code, Cursor, VS Code ou outro cliente MCP lidar com essas chamadas de protocolo.
Buscar metadados OAuth:
GET https://mcp.spala.ai/.well-known/oauth-protected-resource
GET https://mcp.spala.ai/.well-known/oauth-authorization-server
Inicializar 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"
}
}
}
Listar ferramentas:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}
Chamar a integração:
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "spala_get_onboarding",
"arguments": {}
}
}
Chamar o mapa de ferramentas:
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "spala_get_tool_map",
"arguments": {}
}
}
Após a aprovação do OAuth, liste os projetos:
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "project_list",
"arguments": {}
}
}
Conectar o projeto escolhido:
{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "project_connect",
"arguments": {
"projectId": "PROJECT_ID_FROM_PROJECT_LIST"
}
}
}
Ler o contexto seguro do projeto antes da transferência:
{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "project_get_public_context",
"arguments": {
"projectId": "PROJECT_ID_FROM_PROJECT_LIST"
}
}
}
A resposta de project_connect contém um plano de bind único, somente do workspace, para o project MCP. Chame-o uma vez, execute esse plano exatamente e não construa uma URL do project MCP a partir de um 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 o 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. 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.
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 e esquemas exatos das ferramentas do projeto são descobertos no project MCP selecionado em tempo de execução.
Manifesto de instalação
O manifesto de instalação público é:
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 pelo 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