MCP Local Development

Set up a local development environment for Azion MCP server, including cloning, building, and deploying your own instance.

View as Markdown

This guide covers how to set up a local development environment for the Azion MCP server, useful for testing, customization, or contributing to the project.

Prerequisites

Before starting, ensure you have:

Node.js 20+ installed
Yarn package manager
Azion CLI installed: how to download
Git for cloning the repository
OpenAI API Key (required for AI features in local development)

Setup

1. Clone the repository

git clone https://github.com/aziontech/mcp-server.git

cd mcp-server

2. Install dependencies

yarn install

3. Configure environment variables

Create a .env file with your variables: OPENAI_API_KEY="your_openai_key" MCP_COPILOT_SERVER_TOKEN="your_token"

4. Build the server

azion build

Running locally

Start the development server:

azion dev

# Server will be available at http://localhost:3333

Connect your code assistant

Once the server is running, configure your code assistant to use the local endpoint:

# Claude Code example

claude mcp add "azion-mcp-local" "http://localhost:3333" -t http -H "Authorization: Bearer YOUR_PERSONAL_TOKEN"

Personal deployment

Deploy your own instance of the MCP server to Azion Platform.

1. Link your project to your Azion account

Link your project

azion link

2. Deploy

azion deploy

3. Sync your local variables with your remote variables

After deployment, sync the variables used locally with your Azion Environment variables: azion sync

4. Use your personal URL

Update your MCP configuration to use your personal deployment URL instead of the production endpoint.

Testing

Using MCP Inspector

Test your local or personal deployment with MCP Inspector:

# Install MCP Inspector

npm install -g @modelcontextprotocol/inspector

# Run the inspector

npx @modelcontextprotocol/inspector

In the Inspector interface:

Select streamable-http as transport type
Enter your URL: http://localhost:3333 (local) or your personal deployment URL
Add authentication header: Authorization: Bearer YOUR_PERSONAL_TOKEN
Click Connect and test available tools

Test with Node.js directly

npx @modelcontextprotocol/inspector node build/index.js

Project structure

The MCP server project is organized as follows:

Directory/File	Description
`src/index.ts`	Main entry point
`src/core/`	Core functionality
`src/core/tools.ts`	Tool definitions
`src/core/resources.ts`	Resource definitions
`src/core/prompts.ts`	Prompt definitions
`src/middlewares/auth.ts`	Authentication middleware
`src/helpers/utils.ts`	Helper functions
`azion`	Project configuration

Authentication methods

The MCP server supports multiple authentication methods:

Method	Description	Format
Fast Pass Token	Internal token for Azion Copilot	Set via `MCP_COPILOT_SERVER_TOKEN` env var
Personal Tokens	Azion Personal Tokens	Format: `azion[a-zA-Z0-9]{35}` (40 chars)
OAuth Tokens	Bearer tokens from SSO OAuth flow	Validated against `/oauth/userinfo`
JWT Tokens	Bearer tokens for v4 API	Validated against `/v4/account/auth/token`

Token detection order: JWT first for Bearer tokens, then OAuth if JWT fails.

Troubleshooting local development

Server won’t start

Verify Node.js version: node --version (must be 20+)
Check if port 3333 is available
Ensure all dependencies are installed: yarn install

Authentication errors

Verify your Personal Token is valid
Check the OPENAI_API_KEY is set correctly
Ensure the authorization header format is correct

Build failures

# Clean and rebuild

rm -rf build/