Run an MCP server on Azion

Build a Model Context Protocol server with the MCP SDK and Hono, run it as an Azion function, and deploy it with the Azion CLI.

Last updated

View as Markdown Agent setup

You can run your own Model Context Protocol (MCP) server as an Azion function and deploy it with the Azion CLI. To connect a coding agent to the MCP servers that Azion hosts, refer to MCP server quickstart.

MCP is an open specification that uses JSON-RPC to standardize how applications and AI agents communicate. A server exposes three kinds of capabilities: tools (actions), resources (data such as files or API responses), and prompts (shared prompt templates). Any compatible client can list and call the tools, read the resources, and fetch the prompts. A language model can then call your functions and read your data. For more information, refer to the MCP documentation.

The server on this page uses the MCP SDK for TypeScript, @modelcontextprotocol/sdk, which implements the protocol. Hono routes the HTTP requests. The SDK’s WebStandardStreamableHTTPServerTransport answers them over streamable HTTP and works with the Fetch API Request and Response objects that a function receives and returns. For the other transports the protocol defines, refer to Transports.

Prerequisites

  • An Azion account. To create one, refer to Create an account.
  • The Azion CLI, installed and logged in. For the setup, refer to Azion CLI quickstart.
  • Node.js and npm. The CLI runs Azion Bundler with npx to build the project, and npm installs the packages the server imports.

Create and deploy the server

The CLI creates a Hono project from a template. You replace the template’s entry with the MCP server, run it locally, and deploy it. The server uses the high-level McpServer class, which registers each tool, resource, and prompt with one method call.

To create, run, and deploy the server:

Create a Hono project

Run azion init with a name for the project:

azion init --name my-mcp-server

At Choose a preset:, select Hono. You can type Hono to filter the list. At Choose a template:, select Hono Boilerplate. Answer Y to install the dependencies, and n to the local development server and to the deploy. The command prints this output:

Text
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

The project is in the my-mcp-server folder, and its entry is src/index.ts. For every question and the flags that skip them, refer to Azion CLI init.

Install the server's packages

The template installs hono only. Go to the project folder. Install the MCP SDK and version 3 of zod, which the SDK uses:

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

npm adds the two packages to the dependencies of package.json, next to hono.

Write the server

Replace the contents of src/index.ts with the following code. It registers an add tool and a greeting resource, and it answers MCP requests on 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

Each request gets a new server and a new transport with no session ID, so the server keeps no state between requests. An McpServer instance connects to one transport at a time, so the code creates it in getServer() for each request. On an error, the handler logs the error and returns the JSON-RPC error -32603, Internal server error, with HTTP status 500.

Run the server locally

From the project folder, start the local development server:

azion dev

The command builds src/index.ts and serves the function on port 3333:

Text
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.

The server keeps running until you stop it. For the flags of the command, refer to Azion CLI dev.

Check the server locally

In a second terminal, send an MCP initialize request to http://localhost:3333/mcp. The client must accept both JSON and an 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"}}}'

The server answers with one event that holds its name and capabilities:

Text
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}

To list the tools, send a tools/list request to the same 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"}'

The result lists the add tool with the input schema that the code declares:

Text
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}
Deploy the server

Stop the local server, or open a second terminal, and deploy the project from the project folder:

azion deploy

The CLI uploads and builds the project. At the end, it prints the URL of the project’s domain, in the form https://xxxxxxxxxx.map.azionedge.net. For the deploy output and its flags, refer to Azion CLI deploy.

The MCP server runs on Azion’s distributed infrastructure and answers at https://<your-domain>/mcp, where <your-domain> is the domain that azion deploy printed. The first deploy can take several minutes to answer from every location. Later deploys take about two minutes.

Read the deploy configuration

azion deploy creates the resources that azion.config.ts declares, and azion init wrote that file from the Hono template. It builds src/index.ts with the typescript preset and with polyfills turned on. The build writes the function to .edge/functions/index.js, which the file names ./functions/index.js. An application runs that function on every path through a request rule named Execute Function, and a workload serves the application:

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}

The CLI fills each $ name when it creates the resource, and it records the resource IDs in azion/azion.json. For every setting in the file, refer to azion.config.js.

A project folder that azion init did not create has neither file, and azion build refuses to build it with Azion configuration not found. Run azion link in that folder first, then azion build and azion deploy. For the questions azion link asks, refer to Azion CLI link.

Connect a client to the server

An MCP client needs the URL of the server: https://<your-domain>/mcp after the deploy, or http://localhost:3333/mcp while azion dev runs. The path is /mcp because the server’s Hono route is app.post('/mcp', …).

Configure the client as for the Azion MCP servers, with your URL in place of https://docs-mcp.azion.com/mcp. For the client settings, refer to MCP server quickstart. The example server checks no credentials, so the client sends no Authorization header, and anyone with the URL can call its tools.

Use the Server class

The SDK’s low-level Server class replaces the register methods of McpServer with request handlers. You write the handler for each MCP method yourself, which gives you full control over each response. Each capability needs one handler that lists it and one that calls or reads it:

CapabilityMcpServer methodServer list handlerServer call or read handler
ToolsregisterToolListToolsRequestSchemaCallToolRequestSchema
ResourcesregisterResourceListResourcesRequestSchemaReadResourceRequestSchema
PromptsregisterPromptListPromptsRequestSchemaGetPromptRequestSchema

Register each handler with server.setRequestHandler(<schema>, async (request) => { ... }). The schemas come from @modelcontextprotocol/sdk/types.js, which also exports the schemas of the other MCP methods. For more information, refer to the MCP SDK for TypeScript.

The following src/index.ts serves the tools and prompts of the HubSpot MCP server package, @hubspot/mcp-server. It declares the tools, prompts, and resources capabilities and registers four handlers. The route, the transport, and the error handling are the same as in the McpServer server. Add the package to the project before you build it:

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

The HubSpot package reads a HubSpot access token from the PRIVATE_APP_ACCESS_TOKEN environment variable. Without the variable, azion dev builds the project and then stops with HubSpot access token is required.

Run and deploy this server with the same azion dev and azion deploy commands as the McpServer server.

Prepare the server for agents

An agent chooses a tool from its name and description, and calls it with the inputs its schema declares. Check these points before you give the URL to others:

AreaPractice
Tool namesName each tool with a verb and a noun, such as search_docs or create_rule.
Tool descriptionsSay when an agent uses the tool and how.
Tool inputsDeclare a type for every parameter, and validate each value before you use it.
ErrorsReturn a message that says what failed.
Repeated callsMake each tool safe to call more than once.
ResponsesCache data that tools read often, paginate large results, set timeouts on long operations, and compress large responses.
AccessLimit the number of requests each token can send, and log every sensitive operation.
OutputRemove sensitive data from a response before you return it.

For a larger example of a server built with Hono and the MCP SDK, refer to the aziontech/mcp-server repository.

Next steps

How the MCP server worksSee how the Azion MCP servers authenticate agents and answer their requests.Tools and resourcesCompare your server with the tools and resources the Azion MCP servers expose.Azion CLI deployRead the deploy output and the flags that change a deploy.FunctionsLearn how the function that runs your server works.Deploy remote MCP serversMap an existing API to MCP tools, behind WAF and a rate limit, with a log line per tool call.