Plainrouter Sandbox

Teste a conta de anúncios do Meta, a saúde do sinal e as ferramentas de desempenho com dados sintéticos por meio de um endpoint MCP público; nenhuma credencial é necessária.

Ver em plainrouter.com

Servidor MCP hospedado

npx add-mcp 'https://plainrouter.com/mcp/sandbox'

Instala no Claude Code, Codex, Cursor e outros

Documentação

Meta Ads MCP: conecte seu agente ao Plainrouter

Conecte o Claude Code ao servidor MCP de Meta Ads do Plainrouter, leia a saúde do sinal e envie propostas criativas para aprovação em uma conta de anúncios do Meta.

Conecte o Claude Code ao MCP do Plainrouter, verifique uma resposta sintética e, em seguida, configure um token de execução do workspace para sua própria conta de anúncios do Meta. Uma configuração de produção bem-sucedida retorna o workspace e a conta que você selecionou ao emitir o token.

Para tarefas suportadas, requisitos do cliente e limites de aprovação, comece com a introdução ao MCP.

Verifique a conexão do cliente sem uma conta ou token do Plainrouter. Configure seu token do workspace e confirme a primeira leitura da conta.

Escolha seu endpoint MCP

Endpoint	Uso	Credencial
`https://plainrouter.com/mcp/sandbox`	Teste um cliente com quatro ferramentas sintéticas.	Nenhuma
`https://plainrouter.com/mcp`	Leia uma conta aprovada e envie propostas governadas.	Token de execução do workspace para chamadas de ferramentas e dados da conta

O MCP do Plainrouter usa tokens de execução do workspace emitidos por um proprietário ou membro atual. Novas chaves do workspace autorizam um workspace e um nível de Leitura ou Gravação. Ferramentas com escopo de conta selecionam uma conta elegível dentro desse workspace; chaves mais antigas vinculadas à conta mantêm sua restrição original.

Se você está escolhendo entre um segredo de workspace do Signals, um token de execução do workspace ou uma credencial de gerenciamento OAuth, consulte Autenticação e clientes.

Aviso

Credenciais de gerenciamento OAuth não podem autenticar no servidor MCP. Elas podem ler apenas GET /api/v1/agent/context para descoberta de conta. Use um token do workspace para cada chamada de ferramenta MCP.

Antes de começar

Para o sandbox, você só precisa de um cliente com suporte a MCP HTTP remoto. Para produção, você também precisa de:

Uma conta Plainrouter com acesso ao workspace pretendido.
Uma conexão ativa de conta de anúncios do Meta.
Um cliente compatível com MCP que possa enviar um token bearer fixo para um servidor HTTP remoto.
Associação atual à equipe com permissão para o nível de chave que você precisa. Verifique as permissões de chave.
Uma escolha clara da única conta de publicidade que o cliente deve usar.

Para leituras da biblioteca criativa, a conexão do Meta precisa de ads_read ou ads_management. A execução criativa governada precisa de ads_management.

Comece no modo de teste

Em um terminal com Claude Code instalado, adicione o servidor de teste:

claude mcp add --transport http plainrouter-test https://plainrouter.com/mcp/sandbox

Abra o Claude Code no mesmo diretório e execute /mcp para verificar a conexão. Nenhuma conta ou credencial do Plainrouter é necessária. Outros clientes MCP podem usar a mesma URL com transporte HTTP.

O endpoint expõe:

get_account_state
get_signal_health
get_performance
validate_sandbox_event

Toda resposta é sintética e carrega "sandbox": true. O modo de teste não lê dados de tenant, não persiste nada e não contata nenhum provedor de publicidade. Ele não expõe nenhuma ferramenta de proposta, gravação, aprovação, Launcher ou que afete gastos.

Pergunte ao agente:

Use plainrouter-test to call get_account_state, then get_signal_health.
Summarize the synthetic account and signal health. Do not call other tools.

Uma resposta de conta bem-sucedida inclui os seguintes campos. Este é um trecho da resposta sintética, não uma conta de publicidade real:

{
  "sandbox": true,
  "workspace": { "id": 0, "name": "Sandbox Workspace" },
  "ad_account": {
    "id": 0,
    "external_id": "act_SANDBOX",
    "name": "Sandbox Ad Account"
  }
}

Ambas as chamadas devem retornar sem erro de ferramenta. Isso prova que a conexão de teste funciona; não verifica sua conta de produção ou coleta de eventos.

Quando o cliente puder descobrir ou inicializar o servidor, listar ferramentas e chamar uma ferramenta do sandbox, altere a URL do servidor para https://plainrouter.com/mcp e configure um token de execução do workspace. Os três nomes de ferramentas de leitura e suas formas de argumento correspondem à produção.

Nota

O endpoint de produção expõe seu handshake de protocolo, catálogos de ferramentas e recursos e shells de aplicativos estáticos ui:// sem uma credencial. Chamadas de ferramentas e leituras de dados da conta permanecem vinculadas à conta e retornam HTTP 401 sem um token de execução do workspace válido.

Qual protocolo MCP meu cliente deve usar?

O Plainrouter suporta 2026-07-28 até server/discover. Clientes existentes usando initialize podem negociar 2025-11-25 ou 2025-06-18. Deixe seu cliente MCP lidar com o protocolo; a configuração do Claude Code abaixo não precisa de campos de protocolo manuais.

Para um cliente HTTP personalizado, comece com esta solicitação de descoberta do sandbox sem credenciais:

curl https://plainrouter.com/mcp/sandbox \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: server/discover' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "server/discover",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

Verifique se result.supportedVersions inclui 2026-07-28 e result._meta["io.modelcontextprotocol/serverInfo"].name é Plainrouter Sandbox. A descoberta confirma a compatibilidade do protocolo; ela não lê sua conta nem verifica uma chamada de ferramenta.

Para solicitações 2026-07-28 subsequentes:

Campo ou cabeçalho	Requisito
`params._meta`	Inclua a versão do protocolo e as capacidades do cliente em cada solicitação.
`MCP-Protocol-Version`	Corresponda à versão do protocolo em `_meta`.
`Mcp-Method`	Corresponda ao `method` JSON-RPC, como `tools/list` ou `tools/call`.
`Mcp-Name`	Para `tools/call`, corresponda a `params.name`. Para `resources/read`, corresponda a `params.uri`.
`Authorization`	Inclua o token bearer do workspace em toda chamada de ferramenta de produção ou leitura de dados da conta.

As solicitações são sem estado: não aguarde nem exija um cabeçalho de resposta Mcp-Session-Id. Clientes legados sem metadados de protocolo em _meta permanecem no caminho de compatibilidade; não misture os dois formatos de solicitação. Enviar qualquer chave de metadados de protocolo seleciona o caminho de validação moderno.

O cartão do servidor publicado lista o protocolo, as ferramentas e os recursos atuais. A referência de atualização de transporte explica os cabeçalhos modernos e a compatibilidade legada.

Conecte-se com um token do workspace

No Plainrouter, alterne para o workspace pretendido e abra **Configurações → Chaves do workspace**. Digite um nome, escolha Leitura ou Gravação e um prazo de validade, e selecione **Criar chave**. Copie o token completo imediatamente após a emissão. O Plainrouter não pode exibi-lo novamente. No seu cliente MCP, adicione `https://plainrouter.com/mcp` como um servidor HTTP remoto e configure o token como sua credencial bearer. Chame `get_account_state` primeiro. Forneça `account_id` quando houver várias contas elegíveis. Confirme o workspace e a conta retornados antes de continuar.

Consulte Tokens do workspace para seleção de nível, seleção de conta, substituição e revogação.

Configure o Claude Code para sua conta de anúncios do Meta

Adicione esta entrada de servidor ao .mcp.json do seu projeto, preservando quaisquer servidores existentes. O Claude Code expande variáveis de ambiente em cabeçalhos MCP.

{
  "mcpServers": {
    "plainrouter": {
      "type": "http",
      "url": "https://plainrouter.com/mcp",
      "headers": {
        "Authorization": "Bearer ${PLAINROUTER_WORKSPACE_TOKEN}"
      }
    }
  }
}

Forneça PLAINROUTER_WORKSPACE_TOKEN no ambiente do terminal por meio do seu gerenciador de segredos local antes de iniciar o Claude Code. Mantenha a referência da variável no arquivo; não a substitua pelo token nem cole o token em um prompt do agente. Abra /mcp e permita a conexão do projeto quando solicitado.

Comece com um token de Leitura para inspeção da conta e da biblioteca. Use Gravação apenas quando precisar de ferramentas que geram propostas.

Confirme uma conexão de produção somente leitura

Pergunte ao agente:

Use plainrouter to call get_account_state. Show the workspace name and
Meta ad account name and external ID, then stop. If account_id is required,
ask me to select the intended Plainrouter account ID. Do not propose changes.

Verifique se o workspace e a conta de anúncios do Meta retornados correspondem à tarefa pretendida. Para um workspace com várias contas ativas, passe o mesmo account_id selecionado para cada chamada com escopo de conta; use o ID interno da conta do Plainrouter, não o ID externo do Meta. Se corresponderem, peça get_signal_health para inspecionar a entrega de conversões e diagnósticos de correspondência. A ausência de configuração do Signals ou de histórico de medição é um problema de configuração separado; uma leitura de conta bem-sucedida não estabelece rastreamento saudável.

Para os campos retornados e seus significados, consulte a referência de ferramentas MCP.

Permissões

Permissão	Permite
`ad-account.read`	Ler a conta aprovada e seu contexto de Signals do Plainrouter.
`signals.verify`	Gravar um diagnóstico de ingestão de Signal sem identidade e seguro para consentimento. Não conclui a integração.
`actions.propose`	Enviar ações por meio da política do workspace e do pipeline de aprovação.
`creative.read`	Ler a biblioteca criativa da conta aprovada do Meta.
`creative.write`	Preparar ativos criativos e propor alterações criativas. Não contorna `actions.propose`.

O agente pode selecionar apenas contas autorizadas pela chave do workspace; um ID de conta não pode ampliar esse escopo. Ferramentas criativas verificam novamente se os objetos do provedor pertencem à conta aprovada.

Aviso

A permissão de gravação criativa não é autoridade direta de mutação. upload-asset e duplicate-ad-with-creative retornam uma proposta governada. Uma decisão de política posterior ou aprovação humana determina se a execução é enfileirada.

Fluxos de trabalho recomendados

Quando a leitura da conta for bem-sucedida, escolha uma tarefa:

Diagnosticar Signals com uma leitura armazenada. Use verificação de ingestão apenas quando você quiser explicitamente uma gravação de diagnóstico; ela não verifica uma chegada real.
Inspecionar reconciliação armazenada e seus limites de evidência.
Criar uma variante criativa pausada: leia a biblioteca da conta, selecione o anúncio e o ativo de origem, envie uma proposta e revise o link de aprovação.

Peça ao agente para distinguir apenas sugestão, aprovação pendente, bloqueado, aguardando verificação e Landed. A visão geral de ações lista as alterações suportadas.

Exemplo: solicitar uma proposta criativa

Depois de selecionar um anúncio de origem e um ativo da biblioteca criativa da conta aprovada, pergunte:

Use the source ad and asset I selected to propose a paused ad copy.
Summarize the proposed change and show its approval link. Stop for my review.

A ferramenta criativa envia uma proposta ao Plainrouter; ela não altera o Meta durante essa chamada MCP. Em Apenas sugestão, a aprovação registra concordância sem execução. Em um modo executável, o trabalho criativo suportado ainda exige verificações de política e aprovação humana. Uma nova cópia do anúncio permanece PAUSED.

Siga o fluxo de trabalho criativo e o guia de revisão de propostas para os próximos passos. Use a visão geral de ações para verificar as alterações suportadas antes de solicitar uma operação diferente.

Vida útil da autorização e revogação

Os tokens do workspace expiram após 30, 90 ou 365 dias. Em Configurações → Chaves do workspace, o membro emissor pode criar uma substituição dentro de sua função atual e Excluir a chave antiga para revogá-la. A interface atual não tem botão de Rotação de token.

O Plainrouter também limita um token pela função atual do emissor no workspace em cada solicitação. Se a função dessa pessoa não cobrir mais o nível do token, o token para de autenticar nesse nível. Emita um novo token em vez de tentar reutilizar uma credencial cuja autoridade mudou.

Solução de problemas

Um cliente personalizado recebe HTTP `400` ou um erro de protocolo

Para erros JSON-RPC -32020, compare MCP-Protocol-Version, Mcp-Method e, quando necessário, Mcp-Name com o corpo da solicitação. Um cabeçalho obrigatório ausente ou um valor incompatível falha antes da execução da ferramenta. Garanta que seu proxy reverso preserve esses cabeçalhos.

Para -32022, verifique a versão do protocolo em relação à descoberta e use uma versão compatível. Siga o formato completo de solicitação moderna; alterar apenas o cabeçalho de versão não é suficiente. Um 401 de autenticação é uma falha de credencial separada.

O cliente aguarda um ID de sessão

O Plainrouter processa solicitações de forma independente e não retorna Mcp-Session-Id. Atualize um cliente ou transporte personalizado que exija esse cabeçalho. Continue enviando a credencial de portador do workspace em cada solicitação de ferramenta de produção; uma resposta de descoberta bem-sucedida não autoriza chamadas posteriores.

Claude Code não consegue carregar a variável de token

Confirme que PLAINROUTER_WORKSPACE_TOKEN está definido no ambiente que inicia o Claude Code. Reinicie o cliente após fornecê-lo. Mantenha o nome da variável consistente com .mcp.json; não imprima o token para depurar a conexão.

O cliente recebe `401 Unauthorized`

Confirme que o cliente envia o token completo do workspace como credencial de portador e que ele não expirou nem foi revogado. Também confirme que a pessoa emissora ainda possui uma função no workspace que cubra o nível do token.

Se o cliente estiver enviando um token de acesso OAuth, a rejeição é esperada. Substitua-o por um token de execução do workspace.

Uma ferramenta criativa relata permissão ausente

Emita um token com o nível necessário. Use Read para acesso à biblioteca e Write para ferramentas criativas que produzem propostas e lotes de rascunho do Launcher, quando habilitado.

Plainrouter pede para você reconectar o Meta

A conta selecionada pode não ter uma conexão Meta ativa ou o acesso necessário a ads_read ou ads_management. Reconecte o Meta, confirme a mesma conta de anúncios e repita a mesma solicitação idempotente.

A conta errada aparece

Verifique account_id e o workspace da chave. Novas chaves de workspace podem selecionar uma conta ativa pertencente a esse workspace; uma chave mais antiga vinculada a uma conta rejeita uma conta diferente. Siga a seleção de conta.

Ferramentas de sinais mostram configuração necessária

A conta pode estar autorizada corretamente enquanto seu workspace não possui um Signal ou destino ativo. Conclua a configuração de Signals e chame as ferramentas novamente.