Comece com um exemplo em execução
Inicie o exemplo e adapte-o
Crie a API Orders, um banco PostgreSQL e o servidor MCP escolhido no Adios. Enviamos o código, configuramos credenciais JWT separadas e iniciamos as prévias de desenvolvimento.
Iniciar no Adios →Ainda não tem conta? Crie uma e volte a este exemplo. Escolha uma equipe e confira os recursos antes de iniciar. O exemplo completo requer um plano pago com capacidade para dois espaços e um banco de dados.
Crie passo a passo
Seguir o guia manual
Projete a API e o esquema, adicione autenticação JWT, escreva as ferramentas MCP e execute-as nos seus espaços de desenvolvimento. Cada etapa inclui código e comandos.
Seguir as etapas manuais →Explore primeiro o exemplo em execução. OAuth para login de usuários e a implantação em produção vêm depois.
Projete a API para um caso de uso real
Comece pelo objetivo da API. O exemplo permite que um painel interno, um assistente de suporte e uma automação consultem o status de envio de um pedido. Todos usam a mesma operação de negócio. A API controla os dados e as regras de acesso; MCP permite ao cliente de IA descobrir e chamar essa operação.
Defina a primeira versão como somente leitura: um solicitante autorizado fornece um ID de pedido e recebe seu ID e status de envio. Exclua endereços, dados de pagamento e notas internas. Criar pedidos, emitir reembolsos e alterar envios exige endpoints e permissões separados.
- Quem chama a API? Um usuário ou serviço conhecido com um tenant atribuído.
- O que pode fazer? Ler pedidos desse tenant com a permissão orders:read.
- Qual é a responsabilidade da API? Validar a solicitação, verificar o solicitante, aplicar as regras de propriedade e retornar uma resposta estável.
- Qual é a responsabilidade do MCP? Descrever uma ferramenta específica, validar sua entrada e chamar a API com a identidade verificada do solicitante.
Escreva esse contrato antes de escolher um SDK. Isso mantém o site, integrações e ferramentas de IA no mesmo modelo de permissões, sem dar ao cliente de IA acesso direto ao banco.
Projete o esquema e as regras de propriedade
Use PostgreSQL neste exemplo. Um tenant representa uma loja ou organização. Uma identidade associa o sujeito de um token verificado a um tenant e pode ser desativada. Um pedido pertence a um tenant. A API usa essa relação para autorizar a consulta.
| Tabela | Objetivo | Regra de acesso |
|---|---|---|
tenants | Ser proprietário dos dados da organização | Referenciado por identidades e pedidos |
principals | Associar um sujeito verificado a um tenant | Somente identidades ativas podem ler dados |
orders | Armazenar o status de envio | O tenant do solicitante deve corresponder ao do pedido |
-- Demo bootstrap only. Use versioned migrations for an existing production DB.
CREATE TABLE IF NOT EXISTS tenants (
id uuid PRIMARY KEY,
name text NOT NULL
);
CREATE TABLE IF NOT EXISTS principals (
subject text PRIMARY KEY,
tenant_id uuid NOT NULL REFERENCES tenants(id),
active boolean NOT NULL DEFAULT true
);
CREATE TABLE IF NOT EXISTS orders (
tenant_id uuid NOT NULL REFERENCES tenants(id),
id varchar(64) NOT NULL CHECK (id ~ '^[A-Za-z0-9-]{1,64}$'),
status text NOT NULL CHECK (status IN ('pending', 'shipped', 'delivered')),
created_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (tenant_id, id)
);
-- Fictional data; ownership comes from the verified subject, not tool input.
INSERT INTO tenants (id, name) VALUES
('11111111-1111-4111-8111-111111111111', 'Demo shop'),
('22222222-2222-4222-8222-222222222222', 'Other shop')
ON CONFLICT DO NOTHING;
INSERT INTO principals (subject, tenant_id) VALUES
('demo-client', '11111111-1111-4111-8111-111111111111'),
('other-client', '22222222-2222-4222-8222-222222222222')
ON CONFLICT DO NOTHING;
INSERT INTO orders (tenant_id, id, status) VALUES
('11111111-1111-4111-8111-111111111111', 'demo-1001', 'shipped'),
('22222222-2222-4222-8222-222222222222', 'other-1002', 'pending')
ON CONFLICT DO NOTHING;A chave composta permite o mesmo ID de pedido em tenants diferentes. Chaves estrangeiras impedem registros órfãos, e a restrição de status bloqueia estados não aceitos. A consulta liga o sujeito verificado ao tenant e ao pedido; o solicitante não escolhe um tenant na entrada da ferramenta.
A inicialização inclui dois tenants fictícios para testar o isolamento: demo-client pode ler demo-1001, enquanto other-client possui other-1002. A demo executa uma inicialização idempotente ao iniciar. Em um banco de produção existente, use migrações versionadas e separe o provisionamento das solicitações da aplicação.
Defina endpoints, respostas e autenticação JWT
A API pública expõe um endpoint de consulta de pedidos. Uma resposta bem-sucedida é um pequeno objeto JSON com id e status. Mantenha o esquema estável para o site e a ferramenta MCP.
GET /orders/demo-1001
Authorization: Bearer <API-audience JWT>
200 { "id": "demo-1001", "status": "shipped" }
401 missing, invalid or expired JWT
403 valid JWT without orders:read
404 unknown order, inactive identity or another tenant’s order
503 database unavailableA autenticação JWT é o mínimo em todas as implementações abaixo. O cabeçalho bearer transporta o token; compará-lo com uma string aleatória ou apenas decodificá-lo não basta. Verifique a assinatura com um algoritmo permitido, exija emissor e audiência esperados, confira expiração e sujeito e aplique o escopo antes de acessar o banco.
{
"iss": "orders-demo",
"aud": "orders-mcp",
"sub": "demo-client",
"scope": "orders:read",
"iat": 1791498000,
"exp": 1791498900
}A demo controlada usa HS256 com segredos de assinatura separados para API e MCP. Um script exclusivo do operador emite um JWT MCP curto. O servidor verifica esse token e assina um novo JWT de cinco minutos para a audiência orders-api com o mesmo sujeito verificado. A API verifica o segundo token e consulta o tenant do sujeito no PostgreSQL.
Isso torna MCP um gateway confiável com autoridade para assinar tokens da API. Nunca entregue segredos de assinatura a clientes nem exponha o emissor como endpoint público. Fora desse limite de confiança, prefira um provedor OAuth que emita JWTs assimétricos e verifique suas chaves públicas; a seção OAuth mostra o servidor de recursos. JWT é um formato de token; OAuth cuida da autorização delegada e dos fluxos de login.
Não aceite um ID de tenant do cliente como prova de propriedade. Não encaminhe um token com audiência MCP à API. Use tokens curtos, rotacione chaves e use HTTPS em produção. Com vários provedores de identidade, associe emissor e sujeito a uma identidade canônica, em vez de presumir que sujeitos são globalmente únicos.
Emissor JWT de demo exclusivo do operador
import { createHmac } from "node:crypto";
// Operator-only demo issuer. Never expose this script or its key to end users.
const audience = process.argv[2] || "orders-mcp";
if (!["orders-mcp", "orders-api"].includes(audience))
throw new Error("Unknown audience");
const secret =
process.env[audience === "orders-api" ? "API_JWT_SECRET" : "MCP_JWT_SECRET"];
if (!secret || secret.length < 32)
throw new Error("Set the audience's JWT signing secret");
const encode = (value) =>
Buffer.from(JSON.stringify(value)).toString("base64url");
const now = Math.floor(Date.now() / 1000);
const data = `${encode({ alg: "HS256", typ: "JWT" })}.${encode({ iss: "orders-demo", aud: audience, sub: "demo-client", scope: "orders:read", iat: now, exp: now + 900 })}`;
process.stdout.write(
`${data}.${createHmac("sha256", secret).update(data).digest("base64url")}`,
);Implemente a API antes de adicionar MCP
Descompacte os exemplos e abra api/. A implementação Node.js usa jose para verificar JWTs e pg para consultar PostgreSQL. Instale as dependências fixadas com npm ci. A consulta parametrizada liga o sujeito verificado ao seu tenant e retorna apenas pedidos desse tenant.
Dependências da API e comando de inicialização
{
"name": "orders-api",
"private": true,
"type": "module",
"scripts": {
"start": "node init-db.mjs && node server.mjs"
},
"dependencies": {
"jose": "^6.1.0",
"pg": "8.23.1"
}
}import http from "node:http";
import { jwtVerify } from "jose";
import pg from "pg";
const secret = process.env.API_JWT_SECRET;
if (!secret || secret.length < 32 || !process.env.DATABASE_URL) {
throw new Error(
"Set DATABASE_URL and an API_JWT_SECRET of at least 32 characters",
);
}
const key = new TextEncoder().encode(secret);
const pool = new pg.Pool({
connectionString: process.env.DATABASE_URL,
max: 5,
connectionTimeoutMillis: 5000,
statement_timeout: 5000,
});
pool.on("error", () => console.error("Database connection failed"));
await pool.query("SELECT 1");
const server = http.createServer(async (req, res) => {
const send = (status, data) => {
res.writeHead(status, {
"Content-Type": "application/json",
"Cache-Control": "no-store",
});
res.end(JSON.stringify(data));
};
if (req.url === "/healthz" && req.method === "GET") {
try {
await pool.query("SELECT 1");
return send(200, { ok: true });
} catch {
return send(503, { ok: false });
}
}
let principal;
try {
const match = /^Bearer (\S+)$/.exec(req.headers[(process.env.API_AUTH_HEADER || "Authorization").toLowerCase()] || "");
if (!match) throw new Error("Missing access token");
const { payload } = await jwtVerify(match[1], key, {
issuer: "orders-demo",
audience: "orders-api",
algorithms: ["HS256"],
requiredClaims: ["sub", "exp"],
});
if (typeof payload.sub !== "string" || !payload.sub)
throw new Error("Missing subject");
if (
typeof payload.scope !== "string" ||
!payload.scope.split(" ").includes("orders:read")
) {
return send(403, { error: "orders:read permission required" });
}
principal = payload.sub;
} catch {
res.setHeader("WWW-Authenticate", 'Bearer error="invalid_token"');
return send(401, { error: "Invalid or expired access token" });
}
const match = /^\/orders\/([a-zA-Z0-9-]{1,64})$/.exec(req.url || "");
if (req.method !== "GET" || !match) return send(404, { error: "Not found" });
try {
const result = await pool.query(
`SELECT o.id, o.status FROM orders o
JOIN principals p ON p.tenant_id = o.tenant_id
WHERE p.subject = $1 AND p.active = true AND o.id = $2`,
[principal, match[1]],
);
// The same 404 covers unknown IDs and orders outside the caller's tenant.
return result.rows[0]
? send(200, result.rows[0])
: send(404, { error: "Order not found" });
} catch {
return send(503, { error: "Order service unavailable" });
}
});
server.requestTimeout = 10_000;
server.listen(
Number(process.env.PORT || 8081),
process.env.HOST || "127.0.0.1",
);Inicialize o banco de demo
import { readFile } from "node:fs/promises";
import pg from "pg";
if (!process.env.DATABASE_URL) throw new Error("Set DATABASE_URL");
const deadline = Date.now() + 45_000;
let client;
while (true) {
client = new pg.Client({
connectionString: process.env.DATABASE_URL,
connectionTimeoutMillis: 5000,
statement_timeout: 10000,
});
try {
await client.connect();
break;
} catch {
await client.end().catch(() => {});
if (Date.now() >= deadline)
throw new Error(
"Database unavailable. Check its private endpoint and credentials.",
);
await new Promise((resolve) => setTimeout(resolve, 1000));
}
}
try {
await client.query(
await readFile(new URL("./schema.sql", import.meta.url), "utf8"),
);
console.log("Demo database initialized");
} catch {
throw new Error("Could not initialize the demo database");
} finally {
await client.end();
}A API retorna o mesmo 404 para pedidos ausentes e inacessíveis, evitando que sejam descobertos IDs de outro tenant. Sua rota pública de saúde verifica a conexão ao banco sem expor dados nem exigir JWT.
Se já tiver uma API, mantenha seu modelo e verificações de propriedade. Adapte o endpoint e o mapeamento da resposta no handler MCP. Use uma origem e endpoint fixos, sem aceitar URLs arbitrárias da entrada da ferramenta.
Adicione MCP como camada de ferramentas sobre a API
O Model Context Protocol (MCP) oferece aos clientes de IA uma forma padrão de descobrir e chamar ferramentas. Seu servidor descreve uma ferramenta, aceita entradas validadas, executa a operação e retorna um resultado. Sua API REST pode continuar atendendo ao site e a outras integrações.
AI client → HTTPS /mcp → get_order({ order_id: "demo-1001" })
→ GET /orders/demo-1001 → { id: "demo-1001", status: "shipped" }
Client → MCP: MCP_ACCESS_TOKEN, or a user OAuth access token
MCP → API: newly signed API JWT with the verified caller’s subjectO servidor verifica o JWT do cliente antes de criar o handler. Cada chamada API usa um novo JWT com outra audiência e o sujeito verificado. A API continua aplicando as regras de propriedade do banco; MCP não as contorna.
Use Streamable HTTP para um servidor remoto. Stdio é útil quando um cliente desktop inicia um processo local. Estes exemplos HTTP são sem estado e retornam JSON; não exigem armazenamento de sessões nem um fluxo de eventos persistente. Eles expõem /mcp para o protocolo e um endpoint público /healthz para a sonda do ambiente de execução.
Você precisa de PostgreSQL e Node.js 24 para a API, além de Node.js 24, Python 3.13 ou Go 1.25 para o servidor MCP escolhido. Instale a CLI Adios e prepare uma equipe na Adios. Estes exemplos usam os SDKs oficiais de JavaScript 1.32.1, Python 1.30.0 e Go 1.8.0; evite misturá-los com tutoriais de outras versões principais.
Escolha um guia por linguagem
O contrato da API e o modelo de permissões continuam iguais. Siga com a linguagem que você usa: cada guia contém seu código de servidor, dependências, verificações do workspace e manifesto de deploy do Adios.
JavaScript
Use o SDK de JavaScript, esquemas de ferramentas Zod e Express. Inclui o exemplo opcional de servidor de recursos OAuth.
Abrir o guia de JavaScriptPython 3.13Python
Use FastMCP, ferramentas tipadas, HTTPX e um controle JWT ASGI. Mantenha a configuração e o deploy do Python em um só guia.
Abrir o guia de PythonGo 1.25Go
Use o SDK de Go, structs tipadas de entrada e saída e middleware HTTP. Compile e faça o deploy de um único binário de serviço.
Abrir o guia de GoAs três implementações chamam a API compartilhada e verificam os JWTs. O guia de JavaScript também inclui o controle opcional de acesso OAuth do servidor de recursos; Python e Go explicam a autorização necessária antes de permitir o login dos usuários.
Desenvolver em um workspace do Adios
Use uma equipe de desenvolvimento do Adios e PostgreSQL gerenciado. Seu computador apenas envia o código e executa a verificação do cliente; os processos da API e do MCP rodam em workspaces do Adios.
adios login
adios teams
adios teams switch YOUR_DEV_TEAM_ID
export POSTGRES_PASSWORD="$(openssl rand -hex 32)"
export API_JWT_SECRET="$(openssl rand -hex 32)"
export MCP_JWT_SECRET="$(openssl rand -hex 32)"
printf '%s' "$POSTGRES_PASSWORD" | adios secrets set ORDERS_DB_PASSWORD --stdin
printf '%s' "$API_JWT_SECRET" | adios secrets set ORDERS_API_JWT_SECRET --stdin
printf '%s' "$MCP_JWT_SECRET" | adios secrets set ORDERS_MCP_JWT_SECRET --stdin
adios databases create orders-dev-db --template postgres:16 \
--region de --database orders --user orders_api \
--password-secret ORDERS_DB_PASSWORDEspere o banco de dados ficar pronto. Copie sua URL de conexão dos detalhes no Console e salve-a como ORDERS_DEV_DATABASE_URL pela entrada de segredo. Use o host atribuído e verifique se a região do workspace consegue acessá-lo.
adios secrets set ORDERS_DEV_DATABASE_URL --stdin
# Paste the database connection URL, then finish stdin with Ctrl-D.
cp api/adios.dev.yaml api/adios.yaml
adios ws create --name orders-api-dev --json
# Copy workspace_id from the response:
export API_WORKSPACE_ID=YOUR_API_WORKSPACE_ID
(cd api && adios sync "$API_WORKSPACE_ID")
adios ws run start "$API_WORKSPACE_ID" --wait --json
adios ws get "$API_WORKSPACE_ID"Primeiro crie um workspace independente e depois sincronize o código. Criar um workspace a partir do caminho de um projeto pode exigir uma aplicação já implantada; esse fluxo independente permite iniciar o desenvolvimento sem publicar uma versão.
name: orders-api-dev
region: de
build_cmd: npm ci
start_cmd: npm start
runtime:
name: node@24
port: 8081
health_path: /healthz
env:
API_AUTH_HEADER: X-Orders-Token
HOST: 0.0.0.0
PORT: "8081"
DATABASE_URL: secret://ORDERS_DEV_DATABASE_URL
API_JWT_SECRET: secret://ORDERS_API_JWT_SECRETA prévia da API inicializa o esquema de demonstração e inicia o processo Node.js. Copie sua origem HTTPS real do resultado da execução ou do Console. Mantenha este terminal aberto para que o emissor do cliente preserve as chaves de assinatura.
export API_BASE_URL=https://YOUR-API-PREVIEW-HOST
export API_ACCESS_TOKEN="$(node issue-token.mjs orders-api)"
curl --fail "$API_BASE_URL/healthz"
curl --fail -H "Authorization: Bearer $API_ACCESS_TOKEN" \
"$API_BASE_URL/orders/demo-1001"Continue com o guia da sua linguagem para criar o workspace MCP. Atualize os arquivos com adios sync e reinicie a prévia para aplicar as alterações. Uma prévia é um runtime de desenvolvimento, não uma versão publicada da aplicação.
Escolher uma implementação por linguagem →Pare as prévias pelos controles do workspace quando terminar. O banco de dados gerenciado tem seu próprio ciclo de vida; parar uma prévia não o interrompe nem o exclui.
adios ws run stop "$API_WORKSPACE_ID"Adicione OAuth para login e acesso delegado
Os exemplos JWT cobrem uma integração controlada com tokens emitidos pelo operador. Não implementam login, consentimento nem renovação. Adicione OAuth para contas pessoais ou clientes que exigem o fluxo MCP. O modo OAuth deste exemplo aceita JWTs de acesso emitidos pelo provedor.
Seu servidor MCP é o recurso protegido. Um servidor de autorização cuida do login, consentimento e emissão de tokens. Seu provedor OAuth pode fazer isso se aceitar a descoberta e o cadastro necessários aos clientes MCP. A Adios hospeda a aplicação e armazena segredos; o login da CLI não adiciona OAuth automaticamente à aplicação.
- Publique os metadados do recurso em
/.well-known/oauth-protected-resource/mcp, indicando a URL MCP, o servidor de autorização e os escopos aceitos. - Retorne 401 para uma solicitação não autenticada com um cabeçalho
WWW-Authenticateque aponte para esses metadados. - O cliente descobre os metadados OAuth ou OpenID Connect do servidor de autorização. Organize o pré-cadastro, documentos de metadados de cliente ou cadastro dinâmico conforme o suporte do provedor e do cliente.
- O usuário faz login e concede acesso. O cliente usa um fluxo de código de autorização com PKCE e solicita um token para seu recurso MCP.
- Valide a assinatura ou o resultado de introspecção do token, o emissor, a audiência, a expiração e os escopos. Associe o sujeito ao usuário e ao tenant antes de executar uma ferramenta.
Comece com orders:read. Proteja ferramentas de escrita com permissões separadas e confirmação explícita quando o cliente aceitar. Um token de identidade não é um token de acesso à API, e um login válido não permite ler pedidos de todos os clientes.
O guia de JavaScript inclui um controle opcional completo do servidor de recursos com JWT RS256. Ele publica metadados do recurso e verifica tokens do provedor, mas não implementa login, consentimento, registro de clientes nem emissão de tokens.
Seguir a implementação OAuth em JavaScript →Python e Go precisam de um verificador equivalente de tokens do provedor e de metadados do recurso antes de aceitar tokens OAuth de usuários. Um token sozinho não habilita OAuth nas demonstrações JWT.
Uma API de terceiros pode precisar de outra conexão OAuth. Guarde seus refresh tokens com segurança, associe-os ao usuário correto e solicite apenas as permissões necessárias. Segredos de cliente do provedor pertencem aos segredos Adios; URLs do emissor e do JWKS público são configurações comuns.
Referência do protocolo: Especificação de autorização MCP.
Implante PostgreSQL, a API e MCP na Adios
Implante duas aplicações: orders-api e orders-mcp. Elas podem ser publicadas de forma independente. Use a mesma equipe Adios para suas referências a segredos. A região de exemplo é de; escolha uma região disponível adequada aos seus usuários.
Faça login e crie os segredos
Escolha a equipe de publicação e gere novos segredos de assinatura e uma senha de banco de dados. Mantenha seus dados e credenciais separados do desenvolvimento. Adios login autentica a CLI na plataforma.
adios login
adios teams
adios teams switch YOUR_RELEASE_TEAM_ID
export API_JWT_SECRET="$(openssl rand -hex 32)"
export MCP_JWT_SECRET="$(openssl rand -hex 32)"
export POSTGRES_PASSWORD="$(openssl rand -hex 32)"
printf '%s' "$API_JWT_SECRET" | adios secrets set ORDERS_API_JWT_SECRET --stdin
printf '%s' "$MCP_JWT_SECRET" | adios secrets set ORDERS_MCP_JWT_SECRET --stdin
printf '%s' "$POSTGRES_PASSWORD" | adios secrets set ORDERS_DB_PASSWORD --stdinImplante primeiro a API
O manifesto API declara um recurso Postgres gerenciado. A Adios o provisiona e injeta DATABASE_URL no runtime API. A senha referencia um segredo. O comando de inicialização prepara o esquema de demo antes da API; use seu processo normal de migração em produção.
name: orders-api
region: de
replicas: 1
build_cmd: npm ci
start_cmd: npm start
runtime:
name: node@24
port: 8081
health_path: /healthz
resources:
- name: db
template: postgres:16
database: orders
username: orders_api
password: secret://ORDERS_DB_PASSWORD
env:
HOST: 0.0.0.0
PORT: "8081"
API_JWT_SECRET: secret://ORDERS_API_JWT_SECRET
# Adios injects DATABASE_URL for the managed Postgres resource.(cd api && cp adios.release.yaml adios.yaml && adios up)
adios apps get orders-apiadios up compila, implanta e promove uma versão saudável. É um comando de implantação, não uma prévia local. Copie a rota HTTPS real da saída ou do Console e confirme que seu /healthz retorna 200.
Conecte MCP à API implantada
Edite o manifesto no diretório da linguagem escolhida. Substitua https://api.example.com pela origem real da API. Substitua https://mcp.example.com pela origem pública do serviço MCP. São exemplos, não domínios fornecidos pela Adios.
env:
HOST: 0.0.0.0
PORT: "8080"
API_BASE_URL: https://YOUR-API-HOST
PUBLIC_ORIGIN: https://YOUR-MCP-HOST
API_JWT_SECRET: secret://ORDERS_API_JWT_SECRET
MCP_JWT_SECRET: secret://ORDERS_MCP_JWT_SECRETSe ainda não souber o hostname MCP padrão, implante uma vez para obtê-lo, atualize PUBLIC_ORIGIN e implante novamente antes de conectar um cliente. As sondas de saúde funcionam durante essa configuração; MCP aceita apenas a origem configurada. Você também pode verificar um domínio personalizado e adicionar custom_hosts antes da publicação final.
custom_hosts:
- mcp.example.comOs manifestos MCP escutam em 0.0.0.0, expõem a porta 8080 e usam /healthz para verificações de saúde. A Adios encaminha HTTPS à aplicação. Mantenha a sonda independente da autenticação JWT MCP.
Execute o comando de deploy no diretório da implementação escolhida. O guia contém o comando e o manifesto exatos.
Abrir as etapas de deploy da sua linguagem →Execute a verificação do cliente na URL hospedada:
export MCP_ACCESS_TOKEN="$(node issue-token.mjs)"
export MCP_URL=https://YOUR-MCP-HOST/mcp
.client-venv/bin/python check.pyEste tutorial usa uma rota API HTTPS com um JWT de audiência API. Se mover a API para uma rede privada, use o host atribuído pela Adios e verifique a conectividade a partir do MCP. Não deduza um host interno do nome da aplicação. Consulte a referência do manifesto para opções de runtime, segredos e rotas.
Use as ferramentas hospedadas em um cliente de IA
Em um cliente compatível com Streamable HTTP remoto, adicione https://YOUR-MCP-HOST/mcp como URL do servidor. Para os exemplos privados, configure um cabeçalho Authorization: Bearer … pelo mecanismo de segredos ou variáveis de ambiente do cliente. Não cole credenciais em arquivos de configuração compartilhados.
Para OAuth, adicione a mesma URL e complete o login do cliente. Ele deve descobrir os metadados, abrir o login do provedor e receber um token de acesso. Confirme o suporte ao fluxo de cadastro do provedor antes de distribuir a integração.
Verifique se get_order aparece na lista de ferramentas. Peça: “Use o servidor Orders MCP para verificar o status de envio do pedido demo-1001.” O cliente pode chamar a ferramenta e responder que o pedido foi enviado. Verifique a chamada em si, não apenas uma resposta gerada a partir do chat.
check.py demonstra inicialização e chamada por script. Com OAuth, aceita um token de acesso válido em MCP_ACCESS_TOKEN, mas não faz login nem renova tokens; use um cliente compatível com OAuth para isso.
Para um cliente de IA ajudar a implantar este projeto, conecte-o ao Adios MCP. Essa conexão com a plataforma e seu servidor Orders MCP hospedado são integrações independentes com permissões separadas.
Verifique o serviço antes de compartilhá-lo
A rota de saúde API verifica PostgreSQL; a de MCP verifica seu processo. Nenhuma prova que todas as permissões JWT ou OAuth estejam corretas. Após cada publicação, teste inicialização, descoberta e uma chamada permitida conhecida.
- Falha de conexão: verifique a rota, TLS,
/mcpePUBLIC_ORIGIN. O proxy deve preservar o host pretendido e aceitar o transporte escolhido. - 401 ou 403: verifique as credenciais. Para OAuth, verifique emissor, audiência, expiração, escopos e metadados. Teste tokens expirados e com audiência incorreta além de um válido.
- Erro de ferramenta: verifique a URL da API, as permissões de acesso, o tempo limite e o formato da resposta. Não inclua tokens nem respostas privadas nos logs.
- Usuários reais: adicione verificações de tenant e recursos, limites de solicitações, rotação de credenciais e auditoria ligada ao solicitante. Teste que um usuário não possa ler pedidos de outro.
- Mais réplicas: estes exemplos não têm estado de sessão. Se adicionar sessões, notificações ou fluxos persistentes, planeje o estado compartilhado e as rotas.
adios logs orders-api --runtime
adios logs orders-mcp --runtime
adios logs orders-mcp --buildFixe as versões das dependências e repita a verificação do cliente após mudar rotas ou autenticação. Defina permissões e confirmações antes de adicionar ferramentas de escrita.
Perguntas frequentes
Preciso de OAuth para hospedar um servidor MCP?
Uma integração controlada pode usar um JWT verificado de curta duração se o cliente aceitar cabeçalhos de autorização. Para login de usuários, permissões delegadas ou clientes que exigem o fluxo MCP, implemente OAuth. O login da CLI Adios não autentica usuários do seu servidor MCP.
Um servidor MCP pode usar minha API existente?
Sim. Defina ferramentas com esquemas de entrada, valide cada solicitação, chame sua API com uma credencial destinada a ela e retorne resultados estruturados. Verifique as permissões do solicitante sobre o tenant e os recursos antes de acessar dados reais.
Posso hospedar servidores MCP em JavaScript, Python e Go na Adios?
Sim. Os guias vinculados de JavaScript, Python e Go incluem, cada um, um servidor Streamable HTTP completo, arquivos de dependências, endpoints de integridade e um manifesto adios.yaml. Escolha um e faça o deploy junto com a API REST compartilhada.
Qual é a diferença em relação ao Adios MCP?
Este guia cria seu próprio serviço MCP. O Adios MCP permite que um cliente de IA opere workspaces e implantações da Adios. Você pode usar essa conexão com a plataforma para criar e implantar este projeto.