---
title: Endpoint Connection Proxy
description: Conecte clientes MCP diretamente a servidores MCP upstream através do deco Studio
icon: Network
---

import Callout from "../../../../../components/ui/Callout.astro";

## 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
```

<Callout type="warning">
  A forma legada sem escopo `POST /mcp/:connectionId` ainda funciona, mas emite um log de deprecação a cada requisição e será removida. Atualize os clientes para o caminho `/api/:org/...`.
</Callout>

### Parâmetros de path

| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|----------|-------------|
| `org` | `string` | Obrigatório | Slug da organização — imutável durante toda a vida da org |
| `connectionId` | `string` (UUID) | Obrigatório | Identificador único da connection para a qual as requisições serão encaminhadas |

## 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
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"
```

<Callout type="info">
  Clientes que suportam OAuth 2.1 podem usar a URL de resource metadata para descobrir endpoints de autorização e completar o fluxo OAuth automaticamente.
</Callout>

## 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

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

### Exemplo: chamar tool

```json
{
  "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

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

### Resposta de erro

```json
{
  "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:

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

### Tools públicas

Tools podem ser marcadas como públicas usando metadados:

```json
{
  "_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

| Código de status | Descrição | Cenário de exemplo |
|-------------|-------------|------------------|
| `401` | Unauthorized | Nenhum token OAuth ou API key válido fornecido |
| `403` | Forbidden | O usuário não tem permissão para invocar a tool solicitada |
| `404` | Not Found | O Connection ID não existe ou o usuário não tem acesso |
| `500` | Internal Server Error | Erro inesperado durante o processamento da requisição |
| `503` | Service Unavailable | A connection está inativa ou o servidor upstream está inacessível |

## 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:

```json
{
  "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:**
```json
{
  "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:

```typescript
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

| Endpoint | Caso de uso | Tools disponíveis |
|----------|----------|-----------------|
| `/api/:org/mcp/:connectionId` | Acesso direto a um MCP upstream | Apenas tools daquela connection |
| `/api/:org/mcp/gateway/:virtualMcpId` | Conjunto curado de tools para um agent (também conhecido como virtual MCP) | Tools de múltiplas connections, compostas |
| `/api/:org/mcp/self` | Operações de gerenciamento | Apenas tools de gerenciamento do deco Studio |

<Callout type="tip">
  Para a maioria dos casos de uso em produção, use **Agents** (`/api/:org/mcp/gateway/:virtualMcpId`) em vez de connection proxies diretos. Agents permitem controlar quais tools são expostas e compor tools de múltiplas connections atrás de um único endpoint.
</Callout>

## Relacionados

- [**Connections**](/pt-br/studio/connections) - Entendendo a abstração Connection
- [**Agents**](/pt-br/studio/agents) - Componha tools de múltiplas connections em um único endpoint
- [**API Keys**](/pt-br/studio/api-keys) - Configuração de autenticação
- [**Monitoring**](/pt-br/studio/monitoring) - Observabilidade e métricas
