Receitas

Uma receita diz ao Sallyport como chegar a um serviço: seus hosts, a chave que ele usa e a classe de cada chamada.

Nesta página

O que uma receita decide
Leia o catálogo
Como uma chamada é classificada
Verificar uma chave

O que uma receita decide

O catálogo tem uma receita por serviço: GitHub, Stripe, Cloudflare, AWS e mais de cem outros. Uma receita diz onde vai a chave, quais hosts ela alcança e se uma chamada lê, escreve ou destrói.

Uma conexão usa a receita com que foi criada. Senão, o Sallyport escolhe a receita cujo host corresponde, e o host mais exato vence. Um host que nenhuma receita reivindica também funciona, classificado pelo método.

Leia o catálogo

GET /v1/recipes lista o catálogo, com os filtros q (nome, chave ou fornecedor), vendor ou host. GET /v1/recipes/{key} devolve uma. As duas usam uma chave de console, veja API REST.

JSON · GET /v1/recipes/github

{
  "data": {
    "key": "github",
    "name": "GitHub API",
    "vendor": "GitHub",
    "hosts": ["api.github.com"],
    "connection_hosts": ["api.github.com"],
    "connection_domains": [],
    "channel": "http",
    "adapter": "bearer",
    "adapters": ["bearer", "oauth2-ac"],
    "credential_fields": [
      { "name": "value", "label": "Personal access token or installation token", "secret": true, "required": true, "sent_as": [] }
    ],
    "methods": [
      {
        "adapter": "bearer",
        "fields": [
          { "name": "value", "label": "Personal access token or installation token", "secret": true, "required": true, "sent_as": [] }
        ],
        "provider": "",
        "sallyport_app": false,
        "redirect_uri": ""
      },
      {
        "adapter": "oauth2-ac",
        "fields": [],
        "provider": "GitHub",
        "sallyport_app": false,
        "redirect_uri": "https://mcp.sallyport.cloud/callback/upstream"
      }
    ],
    "notes": null,
    "docs_url": "https://docs.github.com/en/rest",
    "create_url": "https://github.com/settings/personal-access-tokens/new",
    "revoke_url": "https://github.com/settings/tokens",
    "scopes_recommended": [],
    "default_profile": "direct",
    "oauth": true,
    "version": 2
  },
  "request_id": "5d0c2f7e8a1b4c6d9e0f1a2b3c4d5e6f"
}

Campo	Significado
`hosts`	Hosts em que o serviço responde. Um `*.` no início cobre todos os subdomínios.
`connection_hosts`, `connection_domains`	Hosts aos quais uma chave nova se conecta como estão, e domínios sob os quais você informa seu próprio endereço, como `acme.zendesk.com`.
`adapter`, `adapters`	Como a chave é apresentada: `bearer`, `basic`, `header`, `api_key`, `aws-sigv4`, `oauth2-ac` para login, e mais alguns.
`credential_fields`	O que uma pessoa digita. `secret` diz se o valor é uma senha. `sent_as` nomeia os cabeçalhos e parâmetros de consulta em que um campo de configuração vai em toda chamada, e fica vazio em qualquer outro campo.
`methods`	Todas as formas de conectar o serviço, na ordem em que o console as oferece. Um método com `provider` é o login no fornecedor.
`create_url`, `revoke_url`, `docs_url`	Onde emitir a chave, onde revogá-la e a referência da API do fornecedor.
`default_profile`	A regra com que começa um par novo de agente e conexão. Todas as receitas dizem `direct`: leitura, escrita e destruição rodam sem perguntar.

As regras de classe e o lugar da chave ficam dentro do Sallyport e não fazem parte desta resposta.

Como uma chamada é classificada

Toda chamada é read, write ou destructive. A regra do agente para essa classe na conexão decide: rodar, perguntar a uma pessoa ou recusar.

O método define o piso: GET, HEAD e OPTIONS leem; POST, PUT e PATCH escrevem; DELETE e qualquer outro método são destrutivos.
As regras da receita são testadas em ordem e vence a primeira que corresponde. Uma regra só sobe a classe, e de um jeito só: um GET com que o fornecedor muda algo vira escrita. Nenhuma regra de receita torna uma chamada destrutiva.
Um segmento de caminho que começa com webhook, hooks, build, trigger, send, invoke, execute, exec ou run torna a chamada pelo menos uma escrita. Uma regra da receita que corresponde ao caminho anula isso.
Uma receita pode listar operações de leitura exatas que viajam como POST, como DescribeInstances da AWS ou uma consulta GraphQL. Elas contam como leitura só quando a requisição inteira se lê de um único jeito.
Requisições GraphQL, JSON-RPC e em lote ficam com a classe mais alta entre suas partes.
Trocas de método como _method e X-HTTP-Method-Override são removidas antes de classificar e enviar a chamada.

Ferramentas de um servidor MCP são classificadas pelo próprio readOnlyHint e destructiveHint, e uma ferramenta que não declara nenhum é uma escrita. Comandos SSH são escritas, exceto uma lista curta de leituras exatas, e comandos como rm ou dd são destrutivos. Veja Comandos SSH. Operações com arquivos em um host SSH são classificadas pelo que fazem: list, stat e read são leituras, write, mkdir e rename são escritas, delete e rmdir são destrutivas. Veja Arquivos por SFTP.

Verificar uma chave

Algumas receitas, o GitHub entre elas, nomeiam uma leitura inofensiva que prova que uma chave funciona: GET /user no GitHub. O Sallyport a roda quando uma chave é salva, quando é trocada e quando você clica em Verificar de novo.

Uma chave que o serviço recusa fica marcada na página dela com a própria mensagem do fornecedor. Uma resposta que não prova nada, como uma permissão faltando, não muda nada.