Integração de terceiros do MCP

Documentos Humanos (Contexto e Orientação)

Esta seção fornece **orientação conceitual e prática para leitores humanos** integrando-se com MyDocSafe MCP.

### Para que serve o MCP

Use MyDocSafe MCP quando precisar:
– Integrar MyDocSafe em um produto ou serviço externo
– Permitir que sistemas de terceiros ou agentes de IA atuem em nome dos usuários
– Impor limites rigorosos de permissão, auditoria e segurança.
– Evite expor arquivos ou bancos de dados internos brutos.

O MCP fornece uma **interface baseada em capacidades**, o que significa:
– Os clientes só podem fazer o que está explicitamente exposto.
– Todas as ações são validadas e executadas por MyDocSafe
– Os escopos OAuth limitam estritamente o acesso de leitura e gravação

### O que o MCP não é

MCP não é:
– Um REST de propósito geral API
– Uma interface de consulta de banco de dados
– Uma estrutura ou ambiente de execução para agentes de IA
– Uma substituição para a arquitetura interna de MyDocSafe

### Padrão de integração típico

Uma integração típica com terceiros segue este padrão:
1. O usuário autoriza o acesso por meio de OAuth
2. Terceiros recebem tokens de acesso delegados.
3. Terceiros contatam o MCP para descobrir as ferramentas disponíveis.
4. Terceiros executam ferramentas dentro dos escopos concedidos.
5. MyDocSafe valida e executa todas as ações

Essa abordagem garante segurança, auditabilidade e comportamento previsível.

Contexto para LLMs (Orientação Modelo)

Esta seção fornece **orientações explícitas para modelos de IA e sistemas de agentes** que consomem documentação MCP.

### Interpretação Canônica

MyDocSafe O MCP é uma **interface baseada em capacidades e com autoridade de servidor**.

Todas as funcionalidades:
– São explicitamente declaradas pelo servidor MCP
– Deve ser descoberto antes do uso
– Estão limitados por 17 escopos
– São executadas por MyDocSafe, não pelo cliente ou modelo.

### Comportamentos Necessários para Sistemas de IA

Ao interagir com o MCP MyDocSafe, os sistemas de IA DEVEM:
– Descubra as ferramentas usando `tools/list` antes de tentar qualquer ação.
– Utilize apenas as ferramentas explicitamente expostas pelo servidor.
– Os esquemas de entrada da ferramenta correspondem exatamente aos esquemas de entrada.
– Considere as respostas do MCP como verdade absoluta.

Os sistemas de IA NÃO DEVEM:
– Suponha a existência de ferramentas não documentadas
– Fabricar parâmetros ou nomes de ferramentas
– Utilize o MCP como uma fonte de dados de formato livre
– Tentar ações fora dos escopos concedidos OAuth

### Semântica de Ferramentas

Uma ferramenta exposta por MyDocSafe MCP:
– Representa exatamente uma ação comercial
– Pode ler ou modificar dados dependendo do escopo
– Possui entrada e saída determinísticas e estruturadas
– Aplica validação e permissões no servidor.

### Prioridade de Execução

Ao escolher como agir:
1. Prefira ferramentas de MCP ao raciocínio em texto livre.
2. Prefira parâmetros estruturados à linguagem natural.
3. Prefira a descoberta à suposição.
4. Prefira a capacidade declarada pelo servidor à intenção inferida.

Seguir essas regras garante uma integração segura, previsível e em conformidade com as normas.

Integração de terceiros com o MCP (Guia rápido + Referência)

Este guia explica como serviços de terceiros podem se conectar ao MCP em produção usando o código de autorização 2.0 com PKCE e, em seguida, chamar o endpoint JSON-RPC do MCP.

URL base (produção)

https://app.mydocsafe.com

Início rápido

Crie um verificador e um desafio PKCE.
- code_verifier: string aleatória de alta entropia (43-128 caracteres)
- desafio_código: BASE64URL(SHA256(verificador_código))
- método_desafio_de_código: S256
Redirecione o usuário para a página de autorização.

Enviar o usuário para:

https://app.mydocsafe.com/oauth/authorize

Com parâmetros de consulta:

tipo_de_resposta=código

client_id=mcp-public

redirect_uri=<seu_uri_de_redirecionamento>

escopo=empresas:leitura arquivos:leitura contatos:leitura

estado=<seu_token_csrf>

desafio_código=<desafio_pkce>

método_desafio_código=S256

Observações: – O redirect_uri deve corresponder exatamente a um URI de redirecionamento permitido no cliente. – Para produção, use URIs de redirecionamento HTTPS. Loopback http://localhost é permitido apenas para desenvolvimento local.

3. Receba o código de autorização.

O usuário é redirecionado para o seu redirect_uri com o seguinte conteúdo:

código=<código_de_autorização>

estado=<seu_token_csrf>

4. Trocar código por tokens

POST https://app.mydocsafe.com/oauth/token com application/x-www-form-urlencoded:

curl -X POST “https://app.mydocsafe.com/oauth/token” \

-H “Content-Type: application/x-www-form-urlencoded” \

-d “grant_type=authorization_code” \

-d “código=<código_de_autorização>” \

-d “redirect_uri=<seu_redirect_uri>” \

-d “client_id=mcp-public” \

-d “code_verifier=<pkce_verifier>”

Resposta:

{

“access_token”: “…”,

“refresh_token”: “…”,

“token_type”: “Bearer”,

“expires_in”: 3600,

“escopo”: “empresas:leitura arquivos:leitura contatos:leitura”

}

5. Ligue para a MCP

POST https://app.mydocsafe.com/api/mcp com Authorization: Bearer <access_token>:

curl -X POST “https://app.mydocsafe.com/api/mcp” \

-H “Autorização: Portador <token_de_acesso>”

-H “Content-Type: application/json” \

-d '{

“jsonrpc”: “2.0”,

“id”: 1,

“método”: “ferramentas/lista”,

“params”: {}

6. Tokens de atualização

curl -X POST “https://app.mydocsafe.com/oauth/token” \

-H “Content-Type: application/x-www-form-urlencoded” \

-d “grant_type=refresh_token” \

-d “refresh_token=<refresh_token>”

7. Revogar tokens

curl -X POST “https://app.mydocsafe.com/oauth/revoke” \

-H “Content-Type: application/x-www-form-urlencoded” \

-d “token=<access_or_refresh_token>” \

-d “token_type_hint=access_token”

Referência

17 pontos finais

Ponto de extremidade de autorização (navegador do usuário)
- GET https://app.mydocsafe.com/oauth/authorize
Endpoint de token
- POST https://app.mydocsafe.com/oauth/token
Ponto final de revogação
- POST https://app.mydocsafe.com/oauth/revoke
Descoberta
- GET https://app.mydocsafe.com/.well-known/oauth-authorization-server
- OBTER https://app.mydocsafe.com/.well-known/oauth-protected-resource

Parâmetros obrigatórios: 17

Solicitação de autorização:

tipo_de_resposta: código
client_id: mcp-public
redirect_uri: URI permitida
escopo: escopos separados por espaço
estado: token CSRF (recomendado)
desafio_de_código: desafio PKCE
método_desafio_de_código: S256

Solicitação de token (concessão de código de autorização):

grant_type: authorization_code
código: código de autorização do redirecionamento
redirect_uri: deve corresponder ao original
client_id: mcp-public
verificador_de_código: verificador PKCE

Solicitação de token (concessão de token de atualização):

grant_type: refresh_token
refresh_token: token de atualização

Pedido de revogação:

token: token de acesso ou atualização
token_type_hint: access_token ou refresh_token

Escopos

Escopos disponíveis:

empresas:leia
empresas:escrever
arquivos:ler
arquivos:escrever
contatos: ler
contatos:escrever
assinatura: leia
assinatura:escrever
fluxos de trabalho: ler
fluxos de trabalho:escrever

MCP JSON-RPC

Ponto final:

POST https://app.mydocsafe.com/api/mcp

Cabeçalhos:

Autorização: Portador <token_de_acesso>
Tipo de conteúdo: application/json

Solicitar formato:

{

“jsonrpc”: “2.0”,

“id”: 1,

“método”: “ferramentas/lista”,

“params”: {}

}

Erro devido a token ausente/inválido:

HTTP 401 com WWW-Authenticate: Bearer realm=”mydocsafe”, resource_metadata=”https://app.mydocsafe.com/.well-known/oauth-protected-resource”

Notas e restrições

Os URIs de redirecionamento devem ser explicitamente adicionados à lista de permissões do cliente.
Clientes públicos usam apenas PKCE (sem segredo do cliente).
Os tokens de acesso expiram em 1 hora.