aziontech · GabrielAzion · Dec 17, 2025
@@ -169,6 +169,68 @@ Create `.vscode/mcp.json` in your project root:
 
 ---
 
+## Warp Terminal
+
+Configure MCP in Warp's settings.
+
+### Configuration
+
+Add to Warp MCP settings:
+
+<Code lang="json" code={`
+{
+    "azion": {
+        "command": "npx",
+        "args": [
+            "mcp-remote",
+            "https://mcp.azion.com",
+            "--header",
+            "Authorization: Bearer YOUR_PERSONAL_TOKEN"
+        ]
+    }
+}
+`} />
+
+---
+
+## Kiro Code
+
+Kiro Code supports MCP through its settings file.
+
+### Setup
+
+Create `.kiro/settings/mcp.json`:
+
+<Code lang="json" code={`
+{
+    "servers": {
+        "azion": {
+            "url": "https://mcp.azion.com",
+            "token": "YOUR_PERSONAL_TOKEN"
+        }
+    }
+}
+`} />
+
+---
+
+## OpenCode
+
+OpenCode uses TOML configuration for MCP servers.
+
+### Setup
+
+Create `.codex/config.toml`:
+
+<Code lang="toml" code={`
+[mcp.servers.azion]
+type = "http"
+url = "https://mcp.azion.com"
+auth = "Bearer YOUR_PERSONAL_TOKEN"
+`} />
+
+---
+
 ## Testing your connection
 
 ### Using MCP Inspector
@@ -231,4 +293,6 @@ This endpoint provides access to all MCP tools and resources for interacting wit
 ## Next steps
 
 - [Explore MCP examples](/en/documentation/devtools/mcp/examples/)
-- [Troubleshooting guide](/en/documentation/devtools/mcp/troubleshooting/)
+- [Troubleshooting guide](/en/documentation/devtools/mcp/troubleshooting/)
+- [Local Development](/en/documentation/devtools/mcp/local-development/)
+- [Cache Testing Guide](/en/documentation/devtools/mcp/cache-testing/)
@@ -321,4 +321,6 @@ The assistant provides:
 ## Next steps
 
 - [Configure MCP](/en/documentation/devtools/mcp/configuration/)
-- [Troubleshooting guide](/en/documentation/devtools/mcp/troubleshooting/)
+- [Troubleshooting guide](/en/documentation/devtools/mcp/troubleshooting/)
+- [Local Development](/en/documentation/devtools/mcp/local-development/)
+- [Cache Testing Guide](/en/documentation/devtools/mcp/cache-testing/)
@@ -0,0 +1,224 @@
+---
+title: MCP Local Development
+description: >-
+  Set up a local development environment for Azion MCP server, including
+  cloning, building, and deploying your own instance.
+meta_tags: 'mcp, local development, setup, deployment, contributing'
+namespace: documentation_devtools_mcp_local_development
+menu_namespace: devtoolsMenu
+permalink: /documentation/devtools/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/azion-copilot-api.git
+cd azion-copilot-api/mcp
+`} />
+
+### 2. Install dependencies
+
+<Code lang="bash" code={`
+yarn install
+`} />
+
+### 3. Configure environment variables
+
+<Code lang="bash" code={`
+# Required for AI features
+export OPENAI_API_KEY="your_openai_key"
+
+# Optional: Fast pass authentication for Azion Copilot integration
+export 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. Create personal configuration
+
+<Code lang="bash" code={`
+# Create personal configuration directory
+mkdir -p azion/personal
+
+# Link your project
+azion link
+
+# Build with personal config
+azion build --config-dir azion/personal
+`} />
+
+### 2. Deploy
+
+<Code lang="bash" code={`
+azion deploy --config-dir azion/personal
+`} />
+
+### 3. Configure environment variables
+
+After deployment, add the required environment variables in Azion Console:
+
+1. Navigate to your application in [Azion Console](https://console.azion.com)
+2. Go to **Environment Variables**
+3. Add `OPENAI_API_KEY` with your OpenAI API key
+
+### 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/production` | Production environment configuration |
+| `azion/stage` | Stage environment configuration |
+
+---
+
+## Configuration directories
+
+The project includes predefined configuration directories:
+
+- **`azion/production`**: Production environment configuration
+- **`azion/stage`**: Stage environment configuration
+- **`azion/personal`**: Your personal configuration (create this)
+
+:::note
+  Never modify the `production` or `stage` directories. Always use a personal configuration for development.
+:::
+
+---
+
+## 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/)
@@ -30,6 +30,17 @@ The Azion MCP server is available at:
 
 **Production URL**: `https://mcp.azion.com`
 
+### Available environments
+
+Choose the appropriate environment based on your needs:
+
+| Environment | URL | Use case |
+|-------------|-----|----------|
+| **Production** | `https://mcp.azion.com` | Production console, main branch |
+| **Stage** | `https://stage-mcp.azion.com` | Stage console, dev branch |
+| **Local Development** | `http://localhost:3333` | Running `azion dev` locally |
+| **Personal Deploy** | Your personal Azion URL | After deploying with `azion deploy --config-dir azion/personal` |
+
 ---
 
 ## Capabilities
@@ -48,6 +59,15 @@ The Azion MCP server provides nine specialized tools:
 | `create_graphql_query` | Build GraphQL queries for analytics |
 | `deploy_azion_static_site` | Get guides for deploying static sites |
 
+### MCP Resources
+
+For clients supporting the MCP Resources Protocol, the following resources are available:
+
+| Resource URI | Description |
+|--------------|-------------|
+| `azion://static-site/deploy/*` | Step-by-step deployment guides |
+| `azion://static-site/test-cache/*` | Cache testing workflows |
+
 ---
 
 ## Requirements
@@ -63,4 +83,6 @@ The Azion MCP server provides nine specialized tools:
 - [MCP Configuration Guide](/en/documentation/devtools/mcp/configuration/)
 - [MCP Examples](/en/documentation/devtools/mcp/examples/)
 - [MCP Troubleshooting](/en/documentation/devtools/mcp/troubleshooting/)
+- [MCP Local Development](/en/documentation/devtools/mcp/local-development/)
+- [MCP Cache Testing](/en/documentation/devtools/mcp/cache-testing/)
 - [Model Context Protocol Specification](https://modelcontextprotocol.io)