MCP Chaos Rig

MCP Chaos Rig

Um servidor MCP local que falha sob demanda. Teste seu cliente contra falhas de autenticação, ferramentas que desaparecem, respostas instáveis e expiração de tokens, tudo a partir de uma interface web.

---

O problema

Você está construindo um cliente MCP. Precisa testar fluxos OAuth, renovação de tokens, descoberta de ferramentas, tratamento de erros e ciclo de vida de sessão. Servidores de produção não falham sob comando. Você precisa de um servidor que faça isso.

O que o Chaos Rig faz

Execute um servidor MCP local onde você controla tudo:

• Quebre a autenticação: force 401s e 500s no meio da sessão, expire tokens sob demanda, rejeite tokens de renovação
• Quebre ferramentas: desative ferramentas para acionar tools/changed, alterne versões de esquema ao vivo
• Quebre a confiabilidade: adicione latência aleatória, faça chamadas de ferramentas falharem em taxas configuráveis
• Veja tudo: o log de requisições ao vivo mostra chamadas JSON-RPC de entrada e respostas SSE de saída, com corpos expansíveis ao clicar

Cenários de teste

Cenário	Como testar
Fluxo de consentimento OAuth 2.1	Use a página de consentimento interativa: aprove, recuse, código inválido, estado adulterado
Autenticação por cabeçalho fixo	Alterne para o modo Headers, configure pares chave-valor, verifique se o cliente os envia
Cabeçalhos ausentes/incorretos	Envie requisições com cabeçalhos ausentes ou incompatíveis — 401 com detalhes
Rejeição de token no meio da sessão	Alterne "Reject OAuth" para 401 ou 500 enquanto o cliente está conectado
Expiração e renovação de token	Defina o TTL do token de acesso para um valor curto, observe o cliente renovar
Rejeitar tokens de renovação	Alterne "Reject refresh tokens" para forçar reautenticação
Cliente errado renovando	Ative "Enforce refresh token ownership" — detecta clientes que perdem credenciais e se re-registram
Sem registro dinâmico	Alterne para "Pre-registered client only" — /register 404s, apenas seu client_id funciona
Credenciais de cliente rotacionadas	Altere o client_id pré-registrado no meio da sessão — o antigo agora falha com invalid_client
Conflito de descoberta de escopo	Defina escopos diferentes no metadata vs cabeçalho WWW-Authenticate, teste qual o cliente confia
Ferramenta desaparecendo	Desative uma ferramenta na aba Tools. Clientes recebem tools/changed
Esquema de ferramenta mudando	Alterne echo ou add entre esquemas v1 e v2
Chamadas de ferramentas instáveis	Defina taxa de falha 0-100%. Chamadas com falha retornam isError: true
Respostas lentas	Ative o modo lento com intervalo de latência configurável
Troca de código PKCE	A página de consentimento OAuth oferece opções "Wrong Code" e "Wrong State"
Ferramentas com banco de dados	Operações CRUD em um banco de dados SQLite real de contatos

---

Início rápido

npx mcp-chaos-rig

Painel de controle em localhost:4100/ui, endpoint MCP em http://localhost:4100/mcp. Requer Node 20+.

Se preferir uma instalação global:

npm install -g mcp-chaos-rig
mcp-chaos-rig

Ou execute a partir do código-fonte:

git clone https://github.com/Typewise/mcp-chaos-rig.git
cd mcp-chaos-rig
npm install
npm run dev

Acesso remoto

Se seu ambiente de produção precisar alcançar o Chaos Rig, exponha-o via túnel (ngrok, Cloudflare Tunnel, etc.) e defina BASE_URL para que os redirecionamentos OAuth sejam resolvidos corretamente:

BASE_URL=https://your-tunnel.example.dev npx mcp-chaos-rig

O modo de autenticação começa em Bearer, então um rig voltado para túnel geralmente quer AUTH_MODE também (none, bearer, headers, oauth). Para OAuth com credenciais pré-registradas, veja Client registration.

Estado de autenticação

Todo o estado está em memória e é redefinido na reinicialização, voltando ao que o ambiente define (AUTH_MODE, OAUTH_CLIENT_MODE, STATIC_*) ou aos padrões integrados. Bearer começa com token test-token-123 (válido até ser alterado). Tokens OAuth expiram conforme o TTL. Tokens de renovação rastreiam a propriedade por cliente quando ativado. Após reiniciar, faça uma renovação com a propriedade desativada para redefinir, depois ative-a.

---

Abas do painel de controle

Server

Configure o modo de autenticação, modo lento (latência aleatória) e ferramentas instáveis (% de taxa de falha).

Modo de autenticação	Comportamento
None	Todas as requisições passam
Bearer	Requer Authorization: Bearer test-token-123
Fixed Headers	Requer pares de cabeçalho chave-valor configurados em cada requisição
OAuth 2.1	Fluxo de autorização completo com página de consentimento interativa

Os modos Bearer, Fixed Headers e OAuth suportam injeção de falhas: force respostas 401 ou 500 para testar o tratamento de erros. O modo começa em Bearer, a menos que AUTH_MODE diga o contrário.

O modo OAuth adiciona controles para registro de cliente, TTL do token de acesso, rejeição de token de renovação e aplicação de propriedade do token de renovação. Os endpoints OAuth são listados em uma seção recolhível.

Registro de cliente

Modo	Comportamento
Registro dinâmico	Clientes se registram em /oauth/register e obtêm credenciais novas (RFC 7591)
Apenas cliente pré-registrado	Apenas o client_id / client_secret configurado é aceito; o registro é desativado

O modo estático reproduz servidores de autorização que emitem credenciais fora de banda (Google, Atlassian, a maioria dos IdPs empresariais):

• registration_endpoint desaparece do metadata well-known
• POST /oauth/register e POST /register retornam 404 registration_not_supported
• qualquer outro client_id recebe invalid_client em /authorize e /token
• um client_secret vazio o torna um cliente público, então o endpoint de token aceita o método de autenticação none
• URIs de redirecionamento devem corresponder exatamente a um configurado, exceto a porta em hosts de loopback (RFC 8252)

O URI de redirecionamento padrão enviado aponta para um cliente local. Testar contra um cliente implantado significa registrar o callback desse cliente, ou /authorize retorna 400 invalid_request — a resposta lista os URIs registrados, já que a flexibilização de porta se aplica apenas a hosts de loopback e callbacks https:// devem corresponder exatamente.

Defina o cliente na inicialização para que um rig voltado para túnel comece pronto:

AUTH_MODE=oauth \
OAUTH_CLIENT_MODE=static \
STATIC_CLIENT_ID=acme-client \
STATIC_CLIENT_SECRET=acme-secret \
STATIC_REDIRECT_URIS=https://platform-api.example.app/api/mcp/oauth/callback \
BASE_URL=https://your-tunnel.example.dev npx mcp-chaos-rig

AUTH_MODE é obrigatório aqui: ele assume o padrão bearer, e os endpoints OAuth retornam 404 até que seja oauth (none, bearer, headers, oauth; qualquer outra coisa falha na inicialização). STATIC_REDIRECT_URIS é separado por vírgulas. Um STATIC_CLIENT_SECRET= vazio inicia um cliente público. Tudo permanece editável na aba Server depois.

Alterar o client_id descarta o anterior, então você pode testar a rotação de credenciais contra um cliente ativo. Defina-o também pela API:

curl -X POST localhost:4100/api/oauth-client -H 'Content-Type: application/json' \
  -d '{"mode":"static","clientId":"acme-client","clientSecret":"acme-secret","redirectUris":["http://localhost:3000/api/mcp/oauth/callback"]}'

Tools

Ative/desative ferramentas. Desativar envia tools/changed para clientes conectados. Algumas ferramentas (echo, add) suportam troca de versão.

Ferramentas disponíveis:

• echo: retorna sua mensagem (v2 adiciona opções de formato)
• add: soma dois números (v2 aceita um array)
• get-time: hora atual do servidor como ISO 8601
• random-number: inteiro aleatório em um intervalo
• reverse: inverte uma string
• typeEcho: ecoa um parâmetro opcional por primitivo de JSON Schema, para verificar se um cliente faz round-trip de cada tipo
• dispute-charge: registra uma disputa de cobrança, retorna um recibo JSON
• list-contacts, get-contact-by-id, get-contact-by-email, search-contacts, create-contact, update-contact, delete-contact: CRUD SQLite

Três ferramentas de esquema grande começam desativadas, para testar como um cliente lida com entradas amplas: submit-customs-declaration (todos os campos obrigatórios), create-product-listing (25 obrigatórios, 25 opcionais), search-properties (50 filtros opcionais).

Contacts

Visualize e redefina o banco de dados SQLite que sustenta as ferramentas de contato. Começa com três registros iniciais.

Log

Log de requisições ao vivo mostrando requisições de entrada e respostas SSE de saída. Exibe timestamp, origem (mcp/auth/sse), método, status, método JSON-RPC, nome da ferramenta e argumentos. Clique em qualquer linha de corpo ou argumentos truncados para expandir. Mantém as últimas 200 entradas.

---

Página de consentimento OAuth

Quando o modo de autenticação é OAuth, o endpoint de autorização mostra uma página de consentimento interativa:

Botão	Resultado
Approve	Redireciona com código de autorização válido
Decline	Redireciona com error=access_denied
Wrong Code	Redireciona com código inválido (troca de token falha)
Wrong State	Redireciona com parâmetro de estado adulterado

---

Links

• npm package
• GitHub repository
• MIT License