> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyxpag.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Servidor MCP da NyxPag

> Conecte assistentes de IA à NyxPag pelo Model Context Protocol para consultar saldo e transações em modo somente leitura, com segurança.

O servidor MCP da NyxPag deixa um assistente de IA compatível com o Model Context Protocol **consultar** o saldo e as transações da sua conta. É **somente leitura**: ele não cria cobrança, não transfere e não decide nada sobre dinheiro.

## Endpoint

O transporte é o **Streamable HTTP** do MCP, e todas as requisições são `POST`:

```text theme={"dark"}
POST https://api.nyxpag.com.br/mcp
```

Autentique cada requisição com uma API Key da NyxPag:

```http theme={"dark"}
Authorization: Bearer nyx_live_sua_chave
```

<Warning>
  A chave dá acesso à leitura de dados financeiros. Crie uma chave **só para o assistente**, com apenas `balance:read` e `transactions:read`, e nunca a cole em prompts compartilhados nem em clientes públicos.
</Warning>

## Sessão

<Steps>
  <Step title="Envie initialize">
    Na primeira conexão, chame o método `initialize` por JSON-RPC 2.0, com `protocolVersion: "2025-06-18"`.
  </Step>

  <Step title="Guarde o MCP-Session-Id">
    A resposta traz o cabeçalho `MCP-Session-Id`. Guarde o valor.
  </Step>

  <Step title="Reenvie o cabeçalho">
    Todas as chamadas seguintes precisam do mesmo `MCP-Session-Id`.
  </Step>
</Steps>

A sessão expira após **30 minutos sem uso** e fica vinculada à chave usada no `initialize`. Trocar de chave exige uma nova sessão.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -i -X POST https://api.nyxpag.com.br/mcp \
    -H "Authorization: Bearer $NYXPAG_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "initialize",
      "params": {
        "protocolVersion": "2025-06-18",
        "capabilities": {},
        "clientInfo": { "name": "meu-app", "version": "1.0.0" }
      }
    }'
  ```

  ```javascript JavaScript theme={"dark"}
  const res = await fetch("https://api.nyxpag.com.br/mcp", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NYXPAG_API_KEY}`,
      "Content-Type": "application/json",
      Accept: "application/json, text/event-stream",
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "initialize",
      params: {
        protocolVersion: "2025-06-18",
        capabilities: {},
        clientInfo: { name: "meu-app", version: "1.0.0" },
      },
    }),
  });

  const sessionId = res.headers.get("MCP-Session-Id");
  ```

  ```python Python theme={"dark"}
  import os
  import requests

  res = requests.post(
      "https://api.nyxpag.com.br/mcp",
      headers={
          "Authorization": f"Bearer {os.environ['NYXPAG_API_KEY']}",
          "Accept": "application/json, text/event-stream",
      },
      json={
          "jsonrpc": "2.0",
          "id": 1,
          "method": "initialize",
          "params": {
              "protocolVersion": "2025-06-18",
              "capabilities": {},
              "clientInfo": {"name": "meu-app", "version": "1.0.0"},
          },
      },
      timeout=15,
  )
  session_id = res.headers.get("MCP-Session-Id")
  ```

  ```php PHP theme={"dark"}
  <?php
  $sessionId = null;
  $ch = curl_init('https://api.nyxpag.com.br/mcp');
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer ' . getenv('NYXPAG_API_KEY'),
          'Content-Type: application/json',
          'Accept: application/json, text/event-stream',
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'jsonrpc' => '2.0',
          'id' => 1,
          'method' => 'initialize',
          'params' => [
              'protocolVersion' => '2025-06-18',
              'capabilities' => new stdClass(),
              'clientInfo' => ['name' => 'meu-app', 'version' => '1.0.0'],
          ],
      ]),
      CURLOPT_HEADERFUNCTION => function ($c, $line) use (&$sessionId) {
          if (stripos($line, 'MCP-Session-Id:') === 0) $sessionId = trim(substr($line, 15));
          return strlen($line);
      },
  ]);
  curl_exec($ch);
  ```
</CodeGroup>

## Ferramentas

Todas são somente leitura.

| Ferramenta | Permissão | O que faz |
| - | - | - |
| `get_balance` | `balance:read` | Saldo disponível e reservado |
| `list_transactions` | `transactions:read` | Lista transações com dados pessoais minimizados |
| `get_transaction` | `transactions:read` | Consulta por ID da NyxPag ou `externalId` |

<Note>
  O MCP **não devolve** CPF, e-mail, QR Code, Copia e Cola nem IDs da processadora. Se precisar desses campos, use a [API REST](/api-reference/transações/verificar-transação) com o mesmo `id`.
</Note>

### get\_balance

Não recebe argumentos.

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": { "name": "get_balance", "arguments": {} }
}
```

### list\_transactions

Aceita `arguments` opcional:

| Campo | Tipo | Valores | Padrão |
| - | - | - | - |
| `page` | integer | A partir de `1` | `1` |
| `limit` | integer | De `1` a `50` | `20` |
| `status` | string | `pending`, `approved`, `failed`, `cancelled`, `refunded` | sem filtro |
| `type` | string | `payment`, `withdrawal` | sem filtro |

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_transactions",
    "arguments": { "page": 1, "limit": 20, "status": "approved", "type": "payment" }
  }
}
```

### get\_transaction

Exige `id`, que pode ser o ID da NyxPag **ou** o seu `externalId`.

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": { "name": "get_transaction", "arguments": { "id": "PEDIDO-1042" } }
}
```

## Chamando uma ferramenta

Depois do `initialize`, chame `tools/call` com o `MCP-Session-Id`:

```bash theme={"dark"}
curl -X POST https://api.nyxpag.com.br/mcp \
  -H "Authorization: Bearer $NYXPAG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Session-Id: $MCP_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": { "name": "get_balance", "arguments": {} }
  }'
```

## Segurança

* A credencial segue sujeita a **IP permitido, verificação de identidade, revogação e limites**, iguais aos da API REST.
* O servidor valida o cabeçalho `Origin` quando ele está presente.
* A cota de **100 requisições por 60 segundos** é da chave e **compartilhada** com a API REST. Um assistente muito falante pode gastar a cota do seu checkout se usarem a mesma chave: use chaves separadas.
* Sessões expiram em 30 minutos sem uso.

<Warning>
  Não use o MCP para decisões autônomas sobre dinheiro. Mesmo sendo somente leitura, o que o assistente lê pode influenciar o que ele recomenda. Toda movimentação de dinheiro deve passar por confirmação humana.
</Warning>

## MCP ou API REST?

| Cenário | Use |
| - | - |
| Assistente de IA consultando saldo e transações | **MCP** |
| Criar cobranças Pix | [API REST](/api-reference/pagamentos/criar-cobrança-pix) |
| Solicitar transferências Pix | [API REST](/api-reference/transferências/solicitar-transferência-pix) |
| Precisar de QR Code, Copia e Cola ou dados do pagador | [API REST](/api-reference/transações/verificar-transação) |
| Backend integrando Pix | [API REST](/quickstart) |

<CardGroup cols={2}>
  <Card title="Gestão de chaves" icon="settings" href="/guides/comece-aqui/api-key">
    Crie uma chave só de leitura para o assistente.
  </Card>

  <Card title="Limites" icon="gauge" href="/guides/confiabilidade/limites">
    A cota compartilhada entre MCP e API REST.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.