# MCP Local Development

import Code from '~/components/Code/Code.astro'

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](https://www.azion.com/en/documentation/products/azion-cli/overview/)
- **Git** for cloning the repository
- **OpenAI API Key** (required for AI features in local development)

---

## Setup

### 1. Clone the repository

<Code lang="bash" code={`
git clone https://github.com/aziontech/mcp-server.git
cd mcp-server
`} />

### 2. Install dependencies

<Code lang="bash" code={`
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

<Code lang="bash" code={`
azion build
`} />

---

## Running locally

Start the development server:

<Code lang="bash" code={`
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:

<Code lang="bash" code={`
# 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

<Code lang="bash" code={`
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:

<Code lang="bash" code={`
# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run the inspector
npx @modelcontextprotocol/inspector
`} />

In the Inspector interface:

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

### Test with Node.js directly

<Code lang="bash" code={`
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

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

### Authentication errors

1. Verify your Personal Token is valid
2. Check the `OPENAI_API_KEY` is set correctly
3. Ensure the authorization header format is correct

### Build failures

<Code lang="bash" code={`
# Clean and rebuild
rm -rf build/
azion build
`} />

---

## Next steps

- [MCP Configuration Guide](/en/documentation/devtools/mcp/configuration/)
- [MCP Examples](/en/documentation/devtools/mcp/examples/)
- [MCP Troubleshooting](/en/documentation/devtools/mcp/troubleshooting/)