Servidor MCP da NyxPag

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:

POST https://api.nyxpag.com.br/mcp

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

Authorization: Bearer nyx_live_sua_chave

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.

Sessão

Envie initialize

Na primeira conexão, chame o método initialize por JSON-RPC 2.0, com protocolVersion: "2025-06-18".

Guarde o MCP-Session-Id

A resposta traz o cabeçalho MCP-Session-Id. Guarde o valor.

Reenvie o cabeçalho

Todas as chamadas seguintes precisam do mesmo MCP-Session-Id.

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.

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" }
    }
  }'

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");

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
$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);

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`

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 com o mesmo id.

get_balance

Não recebe argumentos.

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

{
  "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.

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

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.

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.

MCP ou API REST?

Cenário	Use
Assistente de IA consultando saldo e transações	MCP
Criar cobranças Pix	API REST
Solicitar transferências Pix	API REST
Precisar de QR Code, Copia e Cola ou dados do pagador	API REST
Backend integrando Pix	API REST

Gestão de chaves

Crie uma chave só de leitura para o assistente.

Limites

A cota compartilhada entre MCP e API REST.

​Endpoint

​Sessão

​Ferramentas

​get_balance

​list_transactions

​get_transaction

​Chamando uma ferramenta

​Segurança

​MCP ou API REST?

Gestão de chaves

Limites

Endpoint

Sessão

Ferramentas

get_balance

list_transactions

get_transaction

Chamando uma ferramenta

Segurança

MCP ou API REST?