Servidor MCP

Conecte Claude, ChatGPT, Cursor, VS Code ou qualquer cliente MCP diretamente ao seu workspace.

---

Esta é a forma estratégica de usar SOIS: traga seu próprio agente. Seu workspace Sois AI é um servidor MCP completo, então o agente de IA que você já usa se conecta e raciocina sobre suas ferramentas de workspace diretamente. Cada vez mais, as pessoas nunca entram no console SOIS. Elas dizem ao próprio Claude, ChatGPT, Cursor ou Gemini o que precisam, e ele opera SOIS em nome delas por MCP. O console vira um lugar para visualizar e gerenciar a atividade do agente, não o modo principal de realizar o trabalho.

Qualquer cliente que fala o Model Context Protocol pode se conectar e usar suas ferramentas de workspace: pesquisar contatos, criar tarefas, enviar emails, gerenciar documentos e mais, sem escrever uma única integração. Como seu próprio agente faz o raciocínio, SOIS não gasta IA em seu nome.

Um endpoint. Protocolo padrão. Toda ferramenta que sua conta pode usar, disponível para qualquer cliente compatível.

---

A única URL

Seu workspace expõe um único endpoint MCP:

https://<your-workspace>.sois.ai/api/mcp

O servidor se identifica com a marca do seu workspace (por exemplo "Acme"), então aparece com seu próprio nome no cliente. Tudo abaixo depende dessa única URL.

Existem duas formas de autenticar. OAuth é o caminho recomendado e é o que os conectores no app em Claude e ChatGPT usam: você cola a URL, aprova uma vez e não há token para copiar ou rotacionar manualmente. Um token Bearer mais chave de API também é suportado para scripts, servidores e clientes que não fazem OAuth.

---

Opção A: OAuth 2.1 (recomendada, nada para colar)

Conectores MCP modernos descobrem e completam todo o login para você. Você só fornece a URL.

1. No seu cliente (por exemplo Claude ou ChatGPT), adicione um conector personalizado e cole sua URL MCP: https://<your-workspace>.sois.ai/api/mcp

2. O cliente chama o endpoint sem token e recebe um 401 com um desafio de descoberta:

WWW-Authenticate: Bearer resource_metadata="https://<your-workspace>.sois.ai/.well-known/oauth-protected-resource"

3. O cliente lê esses metadados, encontra o servidor de autorização do seu workspace, se registra automaticamente (Dynamic Client Registration) e abre a tela de login e consentimento.

4. Você aprova a conexão na sua conta SOIS. O cliente recebe um token por PKCE (com um refresh token rotativo) e começa a funcionar. Nenhum token é copiado manualmente.

Por que isso é seguro. O servidor de autorização é o domínio do seu próprio workspace, então os tokens são limitados ao tenant e nunca saem da sua rede. A autorização é sua função: um token concedido nunca pode fazer mais do que você pode, porque toda chamada de ferramenta é verificada por permissão na execução. As strings de escopo são amplas de propósito; o limite real são suas permissões por usuário.

O que o servidor de autorização anuncia:

Você normalmente não chama esses endpoints; um cliente MCP compatível percorre o fluxo automaticamente assim que tem a URL.

---

Opção B: Token Bearer + chave de API (direto ou no lado do servidor)

Para scripts, servidores ou qualquer cliente que não implementa OAuth. Você gera duas credenciais e as envia como headers em toda requisição.

1. Abra Configurações > Conecte seu Agente no seu workspace Sois AI.

2. Escolha seu cliente (Claude Desktop, Cursor, VS Code ou Genérico) e clique em Gerar Credenciais para obter um token Bearer, uma chave de API e um snippet de configuração pronto.

3. Cole a configuração no seu cliente.

{
  "mcpServers": {
    "sois-workspace": {
      "url": "https://<your-workspace>.sois.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN",
        "X-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Cursor usa o mesmo formato em .cursor/mcp.json; VS Code o aninha sob "mcp": { "servers": { ... } } com "type": "http".

Duas credenciais porque identidade e gasto são separados: um token prova quem você é, a chave controla e mede o custo, e qualquer uma sozinha é inútil. (Tokens OAuth carregam sua autorização de forma diferente, então um conector na Opção A não precisa do header X-Api-Key.)

Gere o par programaticamente quando estiver automatizando o onboarding:

curl -X POST "https://<your-workspace>.sois.ai/api/mcp/quick-setup" \
  -H "Authorization: Bearer YOUR_EXISTING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client": "generic"}'

---

Endpoints de descoberta

Um cliente pode aprender tudo o que precisa de três documentos públicos na raiz do seu workspace:

O server card reporta authentication.type como oauth2 e linka para os dois documentos OAuth, que é como um conector sabe iniciar o fluxo na Opção A.

---

Detalhes do protocolo

O endpoint fala Streamable HTTP com JSON-RPC 2.0 (versão da spec 2025-06-18).

Ciclo de vida da sessão

Inclua o Mcp-Session-Id da resposta de initialize em toda requisição posterior.

Métodos suportados

---

Quais ferramentas estão disponíveis

tools/list retorna tudo o que sua conta pode fazer dentro de Sois AI, filtrado pelas suas permissões:

• Contacts: search, create, update, summarise
• Tasks: create, assign, update status, search
• Calendar: list, create, update events, check availability
• Documents: search, create, update content
• Files: browse, upload, download
• Inbox: read, compose, send
• Departments and team: list and manage (admin)
• Installed apps: every tool added by the extensions you have installed (CRM, invoicing, warehouse, custom entities, and so on)

A lista exata depende da função do usuário autenticado e dos apps instalados. As ferramentas são filtradas por permissão e falham de forma fechada, então uma conexão nunca pode chamar algo que o usuário não tem permissão de usar.

O app builder roda sobre esse mesmo endpoint

Não existe um servidor MCP separado para construir apps. As ferramentas do extension-builder vêm como parte do mesmo servidor MCP do workspace e aparecem no mesmo tools/list, com uma condição: elas são admin-gated, então aparecem apenas para contas com capacidade de builder. Se sua conta pode construir apps, sua lista de ferramentas também inclui:

• getExtensionRules, getExtensionFrameSpec (what an app must look like)
• createExtensionProject, listExtensionProjects, getExtensionStatus
• validateExtensionBundle, uploadExtensionBundle

Então construir um app é o mesmo ato que tudo mais: você conecta seu agente ao seu workspace uma vez, e se você for um builder ele pode scaffold, validar e publicar um app junto com rodar seu negócio, tudo pelo único endpoint /api/mcp. Veja Build an app para o fluxo de trabalho.

(Não confundir com o conector público e somente leitura de build-context que um operador pode adicionar para anunciar as capacidades de uma rede; esse é um endpoint separado e não autenticado no domínio da rede, não no seu servidor MCP do workspace.)

---

Orçamento, limites e erros

Erros JSON-RPC padrão se aplicam, mais alguns códigos específicos:

---

Teste sua conexão

curl -X POST "https://<your-workspace>.sois.ai/api/mcp/test" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Api-Key: YOUR_API_KEY"

Retorna se as credenciais funcionam e quantas ferramentas estão visíveis para elas.

---

Trazer seu próprio agente é o caminho estratégico. O Servidor MCP permite que seu próprio cliente de IA raciocine sobre suas ferramentas SOIS diretamente, então SOIS não gasta IA em seu nome. O Chat Agent Gateway é a entrada para chamadores que não têm agente: mensagens em português simples por HTTP, onde o próprio agente de SOIS faz o raciocínio. Use o que melhor se encaixa no seu chamador, ou ambos.

---

Quer conectar Sois a servidores MCP externos em vez disso? Veja o MCP Gateway para conexões de saída.