Execute um MCP server na Azion

Crie um servidor Model Context Protocol com o MCP SDK e o Hono, execute-o como uma function da Azion e faça o deploy dele com a Azion CLI.

Última atualização

Ver como Markdown Configurar agente

Você pode executar o seu próprio servidor Model Context Protocol (MCP) como uma function da Azion e fazer o deploy dele com a Azion CLI. Para conectar um agente de código aos MCP servers que a Azion hospeda, consulte Primeiros passos com o MCP server.

O MCP é uma especificação aberta que usa JSON-RPC para padronizar como aplicações e agentes de IA se comunicam. Um servidor expõe três tipos de capacidade: ferramentas (ações), recursos (dados como arquivos ou respostas de API) e prompts (templates de prompt compartilhados). Qualquer cliente compatível pode listar e chamar as ferramentas, ler os recursos e buscar os prompts. Um modelo de linguagem pode então chamar as suas funções e ler os seus dados. Para mais informações, consulte a documentação do MCP.

O servidor desta página usa o MCP SDK para TypeScript, @modelcontextprotocol/sdk, que implementa o protocolo. O Hono roteia as requisições HTTP. O WebStandardStreamableHTTPServerTransport do SDK responde a elas por streamable HTTP e funciona com os objetos Request e Response da Fetch API que uma function recebe e retorna. Para os outros transportes que o protocolo define, consulte Transports.

Pré-requisitos

  • Uma conta da Azion. Para criar uma, consulte Criar uma conta.
  • A Azion CLI instalada e com login feito. Para a configuração, consulte Primeiros passos com a Azion CLI.
  • Node.js e npm. A CLI executa o Azion Bundler com npx para fazer o build do projeto, e o npm instala os pacotes que o servidor importa.

Crie e faça o deploy do servidor

A CLI cria um projeto Hono a partir de um template. Você substitui a entrada do template pelo MCP server, executa o servidor localmente e faz o deploy dele. O servidor usa a classe de alto nível McpServer, que registra cada ferramenta, recurso e prompt com uma chamada de método.

Para criar, executar e fazer o deploy do servidor:

Crie um projeto Hono

Execute azion init com um nome para o projeto:

azion init --name my-mcp-server

Em Choose a preset:, selecione Hono. Você pode digitar Hono para filtrar a lista. Em Choose a template:, selecione Hono Boilerplate. Responda Y para instalar as dependências e n ao servidor de desenvolvimento local e ao deploy. O comando imprime esta saída:

Texto
01? Choose a preset: Hono [Use arrows to move, type to filter]
02> Hono
03? Choose a preset: Hono
04? Choose a template: [Use arrows to move, type to filter]
05 Azion React Agent
06> Hono Boilerplate
07? Choose a template: Hono Boilerplate
08
09Fetching selected template...
10
11Template successfully fetched
12Template successfully configured
13🤔 Do you want to install project dependencies? This may be required to generate initial configuration file (Y/n) Y
14Installing application dependencies
15
16added 2 packages, and audited 3 packages in 1s
17
18found 0 vulnerabilities
19…
20[Azion] [Build] › ℹ info Using preset: typescript
21[Azion] [Build] › ✔ success Build completed successfully with only azion.config
22[Azion] [IaC] › ✔ success Manifest generated successfully at <project-dir>/.edge/manifest.json
23🤔 Do you want to start a local development server? (y/N) n
24If you want to start a local development server later, run 'azion dev'
25Make sure to change to the new working directory before running building or deploying your project
26🤔 Do you want to deploy your project? (y/N) n
27If you want to deploy your application later, run 'azion deploy'
28Make sure to change to the new working directory before running building or deploying your project
29Your application my-mcp-server was initialized successfully

O projeto fica na pasta my-mcp-server, e a entrada dele é src/index.ts. Para todas as perguntas e as flags que as pulam, consulte Azion CLI init.

Instale os pacotes do servidor

O template instala somente o hono. Vá para a pasta do projeto. Instale o MCP SDK e a versão 3 do zod, que o SDK usa:

Shell
01cd my-mcp-server
02npm install @modelcontextprotocol/sdk zod@3

O npm adiciona os dois pacotes às dependencies do package.json, ao lado do hono.

Escreva o servidor

Substitua o conteúdo de src/index.ts pelo código a seguir. Ele registra uma ferramenta add e um recurso greeting e responde às requisições MCP em POST /mcp:

TypeScript
01import { Hono } from 'hono'
02import type { Context } from 'hono'
03import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
04import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js'
05import { z } from 'zod'
06
07const app = new Hono()
08
09function getServer() {
10 const server = new McpServer({
11 name: "azion-mcp-server",
12 version: "1.0.0"
13 });
14
15 server.registerTool("add",
16 {
17 title: "Addition Tool",
18 description: "Add two numbers",
19 inputSchema: { a: z.number(), b: z.number() }
20 },
21 async ({ a, b }) => ({
22 content: [{ type: "text", text: String(a + b) }]
23 })
24 );
25
26 server.registerResource(
27 "greeting",
28 new ResourceTemplate("greeting://{name}", { list: undefined }),
29 {
30 title: "Greeting Resource",
31 description: "Dynamic greeting generator"
32 },
33 async (uri, { name }) => ({
34 contents: [{
35 uri: uri.href,
36 text: `Hello, ${name}!`
37 }]
38 })
39 );
40
41 return server;
42}
43
44app.post('/mcp', async (c: Context) => {
45 try {
46 const server = getServer();
47 const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
48
49 await server.connect(transport);
50
51 return await transport.handleRequest(c.req.raw);
52 } catch (error) {
53 console.error('Error handling MCP request:', error);
54
55 return c.json({
56 jsonrpc: '2.0',
57 error: { code: -32603, message: 'Internal server error' },
58 id: null,
59 }, 500);
60 }
61});
62
63export default app

Cada requisição recebe um servidor novo e um transporte novo, sem ID de sessão, então o servidor não mantém estado entre as requisições. Uma instância de McpServer se conecta a um transporte por vez, então o código cria a instância em getServer() a cada requisição. Em caso de erro, o handler registra o erro no log e retorna o erro JSON-RPC -32603, Internal server error, com o status HTTP 500.

Execute o servidor localmente

Na pasta do projeto, inicie o servidor de desenvolvimento local:

azion dev

O comando faz o build de src/index.ts e serve a function na porta 3333:

Texto
01…
02[Azion] [Build] › ℹ info Using preset: typescript
03[Azion] [Pre-Build] › ℹ info Starting pre-build...
04[Azion] [Pre-Build] › ℹ info Pre-build completed successfully
05[Azion] [Build] › ℹ info Using entry point(s): src/index.ts
06[Azion] [Build] › ℹ info Starting build...
07[Azion] [Build] › ✔ success Build completed successfully
08[Azion] [Post-Build] › ℹ info Starting post-build...
09[Azion] [Post-Build] › ✔ success Post-build completed successfully
10[Azion] [Server] › ✔ success Function running on port 0.0.0.0:3333, url: http://localhost:3333
11[Azion] [Server] › ℹ info Initial scan complete. Ready for changes.

O servidor continua em execução até você interrompê-lo. Para as flags do comando, consulte Azion CLI dev.

Verifique o servidor localmente

Em um segundo terminal, envie uma requisição MCP initialize para http://localhost:3333/mcp. O cliente precisa aceitar tanto JSON quanto um event stream:

Shell
01curl -s -i -X POST http://localhost:3333/mcp \
02 -H 'Content-Type: application/json' \
03 -H 'Accept: application/json, text/event-stream' \
04 --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

O servidor responde com um evento que contém o nome e as capacidades dele:

Texto
01HTTP/1.1 200 OK
02cache-control: no-cache, no-transform
03connection: keep-alive
04content-type: text/event-stream
05x-accel-buffering: no
06Date: Thu, 01 Jan 2026 12:00:00 GMT
07Transfer-Encoding: chunked
08
09event: message
10data: {"result":{"protocolVersion":"2025-03-26","capabilities":{"tools":{"listChanged":true},"resources":{"listChanged":true}},"serverInfo":{"name":"azion-mcp-server","version":"1.0.0"}},"jsonrpc":"2.0","id":1}

Para listar as ferramentas, envie uma requisição tools/list para a mesma URL:

Shell
01curl -s -i -X POST http://localhost:3333/mcp \
02 -H 'Content-Type: application/json' \
03 -H 'Accept: application/json, text/event-stream' \
04 --data '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

O resultado lista a ferramenta add com o schema de entrada que o código declara:

Texto
01HTTP/1.1 200 OK
02cache-control: no-cache, no-transform
03connection: keep-alive
04content-type: text/event-stream
05x-accel-buffering: no
06Date: Thu, 01 Jan 2026 12:00:00 GMT
07Transfer-Encoding: chunked
08
09event: message
10data: {"result":{"tools":[{"name":"add","title":"Addition Tool","description":"Add two numbers","inputSchema":{"type":"object","properties":{"a":{"type":"number"},"b":{"type":"number"}},"required":["a","b"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"execution":{"taskSupport":"forbidden"}}]},"jsonrpc":"2.0","id":2}
Faça o deploy do servidor

Interrompa o servidor local, ou abra um segundo terminal, e faça o deploy do projeto a partir da pasta do projeto:

azion deploy

A CLI envia o projeto e faz o build dele. No final, ela imprime a URL do domínio do projeto, no formato https://xxxxxxxxxx.map.azionedge.net. Para a saída do deploy e as flags dele, consulte Azion CLI deploy.

O MCP server roda na infraestrutura distribuída da Azion e responde em https://<your-domain>/mcp, em que <your-domain> é o domínio que o azion deploy imprimiu. O primeiro deploy pode levar vários minutos para responder de todas as localidades. Os deploys seguintes levam cerca de dois minutos.

Leia a configuração do deploy

O azion deploy cria os recursos que o azion.config.ts declara, e o azion init escreveu esse arquivo a partir do template Hono. Ele faz o build de src/index.ts com o preset typescript e com os polyfills ativados. O build grava a function em .edge/functions/index.js, que o arquivo chama de ./functions/index.js. Uma aplicação executa essa function em todos os caminhos por meio de uma regra de requisição chamada Execute Function, e um workload serve a aplicação:

TypeScript
01export default {
02 build: {
03 preset: 'typescript',
04 entry: 'src/index.ts',
05 polyfills: true
06 },
07 functions: [
08 {
09 name: '$FUNCTION_NAME',
10 path: './functions/index.js'
11 }
12 ],
13 applications: [
14 {
15 name: '$APPLICATION_NAME',
16 rules: {
17 request: [
18 {
19 name: 'Execute Function',
20 description: 'Execute function for all requests',
21 active: true,
22 criteria: [
23 [
24 {
25 variable: '${uri}',
26 conditional: 'if',
27 operator: 'matches',
28 argument: '^/'
29 }
30 ]
31 ],
32 behaviors: [
33 {
34 type: 'run_function',
35 attributes: {
36 value: '$FUNCTION_NAME'
37 }
38 }
39 ]
40 }
41 ]
42 },
43 functionsInstances: [
44 {
45 name: '$FUNCTION_INSTANCE_NAME',
46 ref: '$FUNCTION_NAME'
47 }
48 ]
49 }
50 ],
51 workloads: [
52 {
53 name: '$WORKLOAD_NAME',
54 active: true,
55 infrastructure: 1,
56 deployments: [
57 {
58 name: '$DEPLOYMENT_NAME',
59 current: true,
60 active: true,
61 strategy: {
62 type: 'default',
63 attributes: {
64 application: '$APPLICATION_NAME'
65 }
66 }
67 }
68 ]
69 }
70 ]
71}

A CLI preenche cada nome com $ quando cria o recurso e registra os IDs dos recursos em azion/azion.json. Para todas as configurações do arquivo, consulte azion.config.js.

Uma pasta de projeto que o azion init não criou não tem nenhum dos dois arquivos, e o azion build se recusa a fazer o build dela com Azion configuration not found. Execute azion link nessa pasta primeiro e depois azion build e azion deploy. Para as perguntas que o azion link faz, consulte Azion CLI link.

Conecte um cliente ao servidor

Um cliente MCP precisa da URL do servidor: https://<your-domain>/mcp depois do deploy, ou http://localhost:3333/mcp enquanto o azion dev está em execução. O caminho é /mcp porque a rota Hono do servidor é app.post('/mcp', …).

Configure o cliente como para os MCP servers da Azion, com a sua URL no lugar de https://docs-mcp.azion.com/mcp. Para as configurações do cliente, consulte Primeiros passos com o MCP server. O servidor de exemplo não verifica nenhuma credencial, então o cliente não envia nenhum header Authorization, e qualquer pessoa com a URL pode chamar as ferramentas dele.

Use a classe Server

A classe de baixo nível Server do SDK substitui os métodos de registro do McpServer por handlers de requisição. Você mesmo escreve o handler de cada método MCP, o que dá a você controle total sobre cada resposta. Cada capacidade precisa de um handler que a lista e de outro que a chama ou a lê:

CapacidadeMétodo do McpServerHandler de listagem do ServerHandler de chamada ou leitura do Server
FerramentasregisterToolListToolsRequestSchemaCallToolRequestSchema
RecursosregisterResourceListResourcesRequestSchemaReadResourceRequestSchema
PromptsregisterPromptListPromptsRequestSchemaGetPromptRequestSchema

Registre cada handler com server.setRequestHandler(<schema>, async (request) => { ... }). Os schemas vêm de @modelcontextprotocol/sdk/types.js, que também exporta os schemas dos outros métodos MCP. Para mais informações, consulte o MCP SDK para TypeScript.

O src/index.ts a seguir serve as ferramentas e os prompts do pacote do MCP server da HubSpot, @hubspot/mcp-server. Ele declara as capacidades tools, prompts e resources e registra quatro handlers. A rota, o transporte e o tratamento de erros são os mesmos do servidor McpServer. Adicione o pacote ao projeto antes de fazer o build:

npm install @hubspot/mcp-server
TypeScript
01import { Server } from '@modelcontextprotocol/sdk/server/index.js';
02import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
03import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
04import { getPrompts, getPromptMessages } from '@hubspot/mcp-server/dist/prompts/index.js';
05import { getTools, handleToolCall } from '@hubspot/mcp-server/dist/tools/index.js';
06import '@hubspot/mcp-server/dist/prompts/promptsRegistry.js';
07import '@hubspot/mcp-server/dist/tools/toolsRegistry.js';
08import { Hono } from 'hono';
09
10// Create a server instance for each request
11function getServer() {
12 const server = new Server({
13 name: 'azion-hubspot-mcp-server',
14 version: '1.0.0',
15 }, {
16 capabilities: {
17 tools: {},
18 prompts: {},
19 resources: {},
20 },
21 });
22
23 // Handler for listing tools
24 server.setRequestHandler(ListToolsRequestSchema, async () => {
25 return {
26 tools: getTools(),
27 };
28 });
29
30 // Handler for calling tools
31 server.setRequestHandler(CallToolRequestSchema, async (request) => {
32 const { name, arguments: args } = request.params;
33 return handleToolCall(name, args);
34 });
35
36 // Handler for listing prompts
37 server.setRequestHandler(ListPromptsRequestSchema, async () => {
38 return {
39 prompts: getPrompts(),
40 };
41 });
42
43 // Handler for getting specific prompt
44 server.setRequestHandler(GetPromptRequestSchema, async (request) => {
45 const { name, arguments: args } = request.params;
46 return getPromptMessages(name, args);
47 });
48
49 return server;
50}
51
52// Create Hono app
53const app = new Hono();
54
55app.post('/mcp', async (c) => {
56 try {
57 const server = getServer();
58 const transport = new WebStandardStreamableHTTPServerTransport({
59 sessionIdGenerator: undefined,
60 });
61
62 await server.connect(transport);
63
64 return await transport.handleRequest(c.req.raw);
65 } catch (error) {
66 console.error('Error handling MCP request:', error);
67 return c.json({
68 jsonrpc: '2.0',
69 error: {
70 code: -32603,
71 message: 'Internal server error',
72 },
73 id: null,
74 }, 500);
75 }
76});
77
78export default app

O pacote da HubSpot lê um access token da HubSpot da variável de ambiente PRIVATE_APP_ACCESS_TOKEN. Sem a variável, o azion dev faz o build do projeto e depois para com HubSpot access token is required.

Execute e faça o deploy deste servidor com os mesmos comandos azion dev e azion deploy do servidor McpServer.

Prepare o servidor para agentes

Um agente escolhe uma ferramenta pelo nome e pela descrição dela e a chama com as entradas que o schema dela declara. Verifique estes pontos antes de passar a URL para outras pessoas:

ÁreaPrática
Nomes das ferramentasDê a cada ferramenta um nome com um verbo e um substantivo, como search_docs ou create_rule.
Descrições das ferramentasDiga quando um agente usa a ferramenta e como.
Entradas das ferramentasDeclare um tipo para cada parâmetro e valide cada valor antes de usá-lo.
ErrosRetorne uma mensagem que diga o que falhou.
Chamadas repetidasTorne cada ferramenta segura para ser chamada mais de uma vez.
RespostasFaça cache dos dados que as ferramentas leem com frequência, pagine resultados grandes, defina timeouts para operações longas e comprima respostas grandes.
AcessoLimite o número de requisições que cada token pode enviar e registre em log toda operação sensível.
SaídaRemova dados sensíveis de uma resposta antes de retorná-la.

Para um exemplo maior de servidor criado com Hono e com o MCP SDK, consulte o repositório aziontech/mcp-server.

Próximos passos

Como o MCP server funcionaVeja como os MCP servers da Azion autenticam os agentes e respondem às requisições deles.Ferramentas e recursosCompare o seu servidor com as ferramentas e os recursos que os MCP servers da Azion expõem.Azion CLI deployLeia a saída do deploy e as flags que mudam um deploy.FunctionsSaiba como funciona a function que executa o seu servidor.Implantar servidores MCP remotosMapeie uma API existente para ferramentas MCP, atrás de WAF e de um rate limit, com uma linha de log por tool call.