# MCP Servers

Integre a Kobana com ferramentas de IA usando o Model Context Protocol (MCP).

**Badges:** MCP | Integração IA | Automação

[Agendar bate-papo](../agendar.md)

---

## O que é MCP?

O Model Context Protocol (MCP) é um padrão aberto para conectar modelos de linguagem a ferramentas e dados externos.

Com MCP, você pode usar a Kobana diretamente em:

- Claude Desktop
- Claude.ai (web)
- Claude Code (CLI)
- ChatGPT
- Cursor
- VS Code (GitHub Copilot)
- Windsurf
- Manus
- Perplexity
- Outras ferramentas compatíveis com MCP

---

## Servidores Disponíveis

A Kobana oferece 10 servidores MCP especializados com 158 ferramentas:

- **kobana-mcp-help** (2 ferramentas) - Acesso ao Centro de Ajuda da Kobana (sem autenticação)
- **kobana-mcp-site** (2 ferramentas) - Busca de conteúdo no site da Kobana (sem autenticação)
- **kobana-mcp-admin** (17 ferramentas) - Certificados, conexões, subcontas e usuários
- **kobana-mcp-charge** (35 ferramentas) - Cobranças Pix, contas Pix, Pix automático e pagamentos
- **kobana-mcp-data** (2 ferramentas) - Consultas de boletos bancários
- **kobana-mcp-edi** (4 ferramentas) - Gerenciamento de caixas EDI
- **kobana-mcp-mailbox** (41 ferramentas) - Caixas postais via S3, Email, SFTP, WhatsApp e Syncthing
- **kobana-mcp-financial** (15 ferramentas) - Contas financeiras, saldos e extratos
- **kobana-mcp-payment** (24 ferramentas) - Pagamentos de boletos, Pix, DARF, impostos e utilidades
- **kobana-mcp-transfer** (16 ferramentas) - Transferências Pix, TED e entre contas internas

> `kobana-mcp-help` e `kobana-mcp-site` não são expostos remotamente — eles não exigem autenticação e devem rodar localmente via npx.

---

## Como conectar

Há duas formas de consumir os servidores MCP da Kobana:

### 1. Remote Custom Connector (recomendado)

Aponte o cliente para o servidor hospedado: `https://mcp.kobana.com.br/{namespace}/mcp`. O endpoint implementa OAuth 2.1 + PKCE + Dynamic Client Registration, então o cliente negocia tudo no navegador automaticamente — você não precisa colar Client ID/Secret.

Cada namespace é um conector separado. Adicione apenas os que você precisa.

### 2. Local stdio via npx

Execute cada servidor localmente como um processo filho a partir do pacote npm. Requer um `KOBANA_ACCESS_TOKEN` pessoal. Funciona em qualquer cliente MCP, inclusive os que ainda não suportam Remote MCP ou OAuth.

```bash
KOBANA_ACCESS_TOKEN=seu_token npx kobana-mcp-financial
```

---

## Endpoints Remotos

| Namespace | URL Remota |
|---|---|
| Admin     | `https://mcp.kobana.com.br/admin/mcp` |
| Charge    | `https://mcp.kobana.com.br/charge/mcp` |
| Data      | `https://mcp.kobana.com.br/data/mcp` |
| EDI       | `https://mcp.kobana.com.br/edi/mcp` |
| Financial | `https://mcp.kobana.com.br/financial/mcp` |
| Mailbox   | `https://mcp.kobana.com.br/mailbox/mcp` |
| Payment   | `https://mcp.kobana.com.br/payment/mcp` |
| Transfer  | `https://mcp.kobana.com.br/transfer/mcp` |

Para sandbox, troque `mcp.kobana.com.br` por `mcp.sandbox.kobana.com.br`.

---

## Configuração por Cliente

### Claude Desktop

**Remoto (recomendado).** Settings → **Connectors → Add Custom Connector**. Cole a URL, deixe os campos avançados em branco, clique em Add e conclua o login Kobana no navegador.

- URL: `https://mcp.kobana.com.br/financial/mcp`

**Local (stdio).** Edite o arquivo de configuração:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "kobana-financial": {
      "command": "npx",
      "args": ["-y", "kobana-mcp-financial"],
      "env": {
        "KOBANA_ACCESS_TOKEN": "seu_token",
        "KOBANA_API_BASE_URL": "https://api.kobana.com.br"
      }
    }
  }
}
```

### Claude.ai (web)

Customize → **Connectors → +** (Add custom connector). Cole a URL, deixe Advanced settings em branco e clique em Add. O OAuth acontece em uma nova aba.

- URL: `https://mcp.kobana.com.br/financial/mcp`

Disponível em Free, Pro, Max, Team e Enterprise. Contas Free são limitadas a um conector custom por vez.

### Claude Code (CLI)

```bash
# Remoto com OAuth automático
claude mcp add --transport http kobana-financial https://mcp.kobana.com.br/financial/mcp

# Local stdio com token pessoal
claude mcp add kobana-financial -- npx -y kobana-mcp-financial \
  --env KOBANA_ACCESS_TOKEN=seu_token
```

### ChatGPT (Pro/Business/Enterprise/Edu)

1. Settings → **Apps & Connectors → Advanced settings** → ative **Developer Mode**.
2. Em **Apps & Connectors**, clique em **Add → MCP server**.
3. Preencha:
   - URL: `https://mcp.kobana.com.br/financial/mcp`
   - Authentication: `OAuth`
   - Name: `Kobana Financial`
4. Salve. O ChatGPT abre o navegador para concluir o login.

### Cursor

UI: Settings → **Tools & MCP → New MCP Server**. Escolha HTTP e cole a URL.

Ou edite `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "kobana-financial": {
      "url": "https://mcp.kobana.com.br/financial/mcp"
    }
  }
}
```

### VS Code (GitHub Copilot / MCP)

Edite `.vscode/mcp.json` (workspace) ou seu `mcp.json` de usuário:

```json
{
  "servers": {
    "kobana-financial": {
      "type": "http",
      "url": "https://mcp.kobana.com.br/financial/mcp"
    }
  }
}
```

### Windsurf

Edite `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "kobana-financial": {
      "serverUrl": "https://mcp.kobana.com.br/financial/mcp"
    }
  }
}
```

> Windsurf usa `serverUrl` (não `url`). Após salvar, feche o Windsurf completamente e reabra — fechar a janela do editor não recarrega os MCP servers.

### Manus

Settings → **Connectors → Add Connectors → Custom MCP**:

```json
{
  "mcpServers": {
    "kobana-financial": {
      "transport": "http",
      "url": "https://mcp.kobana.com.br/financial/mcp"
    }
  }
}
```

Se o handshake OAuth falhar, use um header `Authorization` explícito como fallback.

### Perplexity (Pro/Max/Enterprise)

Settings → **Connectors → Add → Custom Connector**:

- Name: `Kobana Financial`
- URL: `https://mcp.kobana.com.br/financial/mcp`
- Authentication: `OAuth 2.0`
- Transport: `Streamable HTTP`

Deixe Client ID / Client Secret em branco — o Perplexity descobre os endpoints via Dynamic Client Registration.

---

## MCP Servers vs Agent Skills

| Aspecto | MCP Servers | Agent Skills |
|---------|-------------|--------------|
| O que é | Ferramentas e APIs para executar ações | Instruções e conhecimento para o agente |
| Quando usar | Para dar capacidade de fazer algo | Para ensinar como fazer algo |
| Exemplo | "Use create_charge_pix para criar cobranças" | "Siga estas etapas para criar uma cobrança Pix" |
| Configuração | Configuração de servidor | Upload de arquivo SKILL.md |

Skills podem instruir o agente a usar ferramentas MCP corretamente — eles são complementares.

[Ver Agent Skills](agent-skills.md)

---

## Variáveis de Ambiente

- **KOBANA_ACCESS_TOKEN**: Token de acesso da API (obrigatória para o modo local stdio)
- **KOBANA_API_BASE_URL**: URL base da API (opcional, padrão: `https://api.kobana.com.br`)

---

## Documentação

[Ver documentação completa no GitHub](https://github.com/universokobana/kobana-mcp-servers)

---

[Agendar bate-papo](../agendar.md)