Endpoint Connection Proxy

Visão geral

O endpoint Connection Proxy permite que clientes MCP (como Cursor, Claude Desktop ou aplicações customizadas) se conectem diretamente a um servidor MCP upstream específico através do deco Studio. Esse endpoint atua como um proxy seguro e observável que lida com autenticação, autorização, gerenciamento de credenciais e monitoramento.

Endpoint

O caminho canônico é escopado por organização:

POST https://your-studio-instance.com/api/:org/mcp/:connectionId

Parâmetros de path

Autenticação

O Connection Proxy requer autenticação usando uma das opções:

• OAuth Bearer Token: Authorization: Bearer <token>
• API Key: Authorization: Bearer <api_key>

Quando não autenticado, o endpoint retorna uma resposta 401 com um header WWW-Authenticate contendo metadados de descoberta OAuth:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="mcp",resource_metadata="https://your-studio-instance.com/api/:org/mcp/:connectionId/.well-known/oauth-protected-resource"

Como funciona

Quando um cliente envia uma requisição MCP através do Connection Proxy:

1. Autenticação: o deco Studio verifica as credenciais do cliente (token OAuth ou API key)
2. Busca da connection: o deco Studio recupera a configuração da connection e verifica se está ativa
3. Autorização: o deco Studio verifica se o cliente tem permissão para invocar a tool solicitada
4. Injeção de credenciais: o deco Studio descriptografa as credenciais armazenadas e as injeta na requisição upstream
5. Encaminhamento da requisição: o deco Studio encaminha a requisição MCP para o servidor upstream
6. Monitoramento: o deco Studio registra métricas (duração, status, erros) para observabilidade
7. Retorno da resposta: o deco Studio retorna a resposta do servidor upstream ao cliente

Formato da requisição

O Connection Proxy aceita requisições padrão do protocolo MCP. O corpo da requisição deve ser uma mensagem JSON-RPC 2.0 seguindo a especificação MCP.

Exemplo: listar tools

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Exemplo: chamar tool

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "github_create_issue",
    "arguments": {
      "repo": "myorg/myrepo",
      "title": "Bug report",
      "body": "Description of the bug"
    }
  }
}

Formato da resposta

As respostas seguem o formato padrão do protocolo MCP:

Resposta de sucesso

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Issue created successfully: #123"
      }
    ]
  }
}

Resposta de erro

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32603,
    "message": "Tool execution failed"
  }
}

Autorização

O Connection Proxy aplica autorização granular usando o sistema de permissões do deco Studio:

• Permissões por tool: usuários precisam ter permissão explícita para cada tool que invocam
• Escopo por connection: as permissões são escopadas para a connection específica
• Baseadas em papéis: as permissões são herdadas dos papéis do usuário e das configurações da organização

Formato das permissões

As permissões são armazenadas no formato:

{
  "<connectionId>": ["tool_name_1", "tool_name_2"]
}

Tools públicas

Tools podem ser marcadas como públicas usando metadados:

{
  "_meta": {
    "mcp.studio": {
      "public_tool": true
    }
  }
}

Tools públicas permitem acesso não autenticado e ignoram as verificações de autorização. A chave legada de metadados mcp.mesh continua sendo aceita por compatibilidade.

Respostas de erro

Monitoramento e observabilidade

Cada requisição pelo Connection Proxy gera:

Métricas

• Histogramas de duração: connection.proxy.duration
• Contadores de requisição: connection.proxy.requests
• Contadores de erro: connection.proxy.errors

Todas as métricas incluem labels:

• connection.id: o UUID da connection
• tool.name: a tool sendo invocada
• status: success ou error

Traces

Spans OpenTelemetry são criados para:

• mcp.proxy.callTool: invocações de tool

Os traces incluem atributos:

• connection.id: identificador da connection
• tool.name: nome da tool
• request.id: identificador único da requisição

Opções de configuração

Connections podem ser configuradas com:

Timeout

O timeout padrão para chamadas de tool é de 5 minutos (300.000ms). Pode ser ajustado por connection com base nas características de execução da tool.

Headers customizados

Connections podem incluir headers HTTP customizados para autenticação ou roteamento:

{
  "connection_headers": {
    "headers": {
      "X-Custom-Header": "value"
    }
  }
}

Casos de uso

Acesso direto via MCP

Conecte o Cursor ou o Claude Desktop diretamente a um MCP upstream específico:

Configuração no Cursor:

{
  "mcpServers": {
    "github-production": {
      "url": "https://studio.example.com/api/my-org/mcp/conn_abc123",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Clientes específicos por tool

Construa clientes customizados que precisam acessar as tools de um servidor MCP específico sem passar por um agent:

const response = await fetch('https://studio.example.com/api/my-org/mcp/conn_abc123', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'database_query',
      arguments: { query: 'SELECT * FROM users LIMIT 10' }
    }
  })
});

Isolamento multi-tenant

Cada connection é escopada por organização, fornecendo isolamento natural entre tenants:

Organization A → conn_123 (GitHub Org A) → GitHub Tools (Org A only)
Organization B → conn_456 (GitHub Org B) → GitHub Tools (Org B only)

Estados da connection

Connections têm um campo status que afeta o comportamento do proxy:

• active: a connection está pronta para encaminhar requisições
• inactive: a connection está desabilitada; o proxy retorna erro 503
• error: a connection tem problemas de configuração; o proxy pode falhar

Considerações de segurança

Tratamento de credenciais

• Criptografadas em repouso: credenciais são armazenadas criptografadas usando AES-256-GCM
• Descriptografadas just-in-time: credenciais só são descriptografadas no momento do proxy da requisição
• Nunca expostas aos clientes: clientes nunca recebem as credenciais upstream

Validação de requisição

• Validação de schema: argumentos de tool são validados contra schemas de entrada
• Rate limiting: (Planejado) limites de taxa por connection e por usuário
• Audit logging: todas as invocações de tool são registradas com a identidade do usuário

Segurança de rede

• TLS obrigatório: todas as conexões com servidores upstream usam HTTPS
• Validação de certificado: certificados SSL são validados por padrão
• Proxy headers: servidores upstream recebem requisições autenticadas com credenciais

Comparação com outros endpoints

Relacionados

• Connections - Entendendo a abstração Connection
• Agents - Componha tools de múltiplas connections em um único endpoint
• API Keys - Configuração de autenticação
• Monitoring - Observabilidade e métricas