### Install Docker Compose

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Download the latest Docker Compose binary and make it executable. This installs Docker Compose to /usr/local/bin/docker-compose.

```bash
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```

--------------------------------

### Enable Nginx Site and Start Service

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Enable the newly created Nginx site configuration, disable the default site, test the Nginx configuration, and then enable and start the Nginx service.

```bash
# Enable the site
sudo ln -s /etc/nginx/sites-available/metamcp /etc/nginx/sites-enabled/

# Remove default site
sudo rm /etc/nginx/sites-enabled/default

# Test nginx configuration
sudo nginx -t

# Start nginx
sudo systemctl enable nginx
sudo systemctl start nginx
```

--------------------------------

### Clone & Setup MetaMCP

Source: https://docs.metamcp.com/en

Clone the MetaMCP repository and set up environment variables.

```bash
git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
cp example.env .env
```

--------------------------------

### Start PostgreSQL Database

Source: https://docs.metamcp.com/en/development

Start the PostgreSQL database using Docker Compose. This is required for the backend services. You can start only the database or the full stack.

```bash
docker compose up -d postgres
```

```bash
docker compose up -d
```

--------------------------------

### Start MetaMCP with Docker

Source: https://docs.metamcp.com/en

Start MetaMCP services using Docker Compose in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Install Project Dependencies

Source: https://docs.metamcp.com/en/development

Install all project dependencies for the monorepo using pnpm. This command should be run after cloning the repository.

```bash
pnpm install
```

--------------------------------

### Run Development Server

Source: https://docs.metamcp.com/en/development

Start the development server for both the frontend and backend. This command allows you to test your changes locally in real-time.

```bash
pnpm dev
```

--------------------------------

### STDIO Server with Environment Variables

Source: https://docs.metamcp.com/en/concepts/mcp-servers

Example of configuring a STDIO server with specific environment variables, such as timezone settings.

```json
{
  "name": "TimeServer",
  "type": "STDIO",
  "command": "uvx",
  "args": ["mcp-server-time", "--local-timezone=America/New_York"],
  "env": {
    "TZ": "America/New_York"
  }
}
```

--------------------------------

### Update and Install Essential Packages

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Update the package list and upgrade existing packages, then install essential tools like curl, wget, git, UFW firewall, Nginx, and Certbot.

```bash
apt update && apt upgrade -y
```

```bash
apt install -y curl wget git ufw nginx certbot python3-certbot-nginx
```

--------------------------------

### Set Up Environment Variables

Source: https://docs.metamcp.com/en/development

Copy the example environment file to `.env` to configure your local development environment. Modify the `.env` file with your specific settings.

```bash
cp example.env .env
```

--------------------------------

### Install Docker Prerequisites

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Update the package index and install packages required for adding Docker's official repository.

```bash
sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
```

--------------------------------

### Start MetaMCP Services

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Pull the necessary Docker images and start the MetaMCP services in detached mode. Includes commands to check service status and view logs.

```bash
# Pull images and start services
docker-compose up -d

# Check if services are running
docker-compose ps

# View logs if needed
docker-compose logs -f
```

--------------------------------

### Install Docker CE

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Install the Docker Community Edition (CE) package after updating the package index.

```bash
sudo apt update
sudo apt install -y docker-ce
```

--------------------------------

### Basic mcp.json Setup for Cursor

Source: https://docs.metamcp.com/en/integrations/cursor

Configure the mcp.json file with your MetaMCP server URL for basic integration.

```json
{
  "mcpServers": {
    "MetaMCP": {
      "url": "http://localhost:12008/metamcp/your-endpoint-name/mcp"
    }
  }
}
```

--------------------------------

### Create and Configure Non-Root User

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Create a new user for managing MetaMCP and grant it sudo privileges. Switch to this new user to continue setup.

```bash
adduser metamcp
usermod -aG sudo metamcp
# Switch to the new user
su - metamcp
```

--------------------------------

### Example Endpoint URLs

Source: https://docs.metamcp.com/en/concepts/endpoints

These are example URLs for accessing an endpoint using different transport protocols. Ensure you replace 'your-metamcp.com' and 'my-endpoint' with your actual domain and endpoint name.

```text
https://your-metamcp.com/metamcp/my-endpoint/sse
```

```text
https://your-metamcp.com/metamcp/my-endpoint/mcp
```

```text
https://your-metamcp.com/metamcp/my-endpoint/api
```

```text
https://your-metamcp.com/metamcp/my-endpoint/api/openapi.json
```

--------------------------------

### Example MCP Server Configuration

Source: https://docs.metamcp.com/en/concepts/mcp-servers

A basic JSON configuration for an MCP Server, specifying its name, type, command, and arguments.

```json
{
    "name": "HackerNews",
    "type": "STDIO", 
    "command": "uvx",
    "args": ["mcp-hn"],
    "description": "Access HackerNews stories and comments"
  }
```

--------------------------------

### Clone MetaMCP Repository

Source: https://docs.metamcp.com/en/quickstart

Clone the MetaMCP project from GitHub and navigate into the project directory. This is the first step in the installation process.

```bash
git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
```

--------------------------------

### mcp.json Setup with API Key Authentication

Source: https://docs.metamcp.com/en/integrations/cursor

Set up mcp.json to include an Authorization header for API key authentication.

```json
{
  "mcpServers": {
    "MetaMCP": {
      "url": "http://localhost:12008/metamcp/your-endpoint-name/mcp",
      "headers": {
        "Authorization": "Bearer sk_mt_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Custom Dockerfile for Dependencies

Source: https://docs.metamcp.com/en/concepts/mcp-servers

Example Dockerfile to extend the base MetaMCP image with custom system packages, Python, or Node.js dependencies.

```dockerfile
FROM metamcp:latest

# Install Python dependencies
RUN pip install requests beautifulsoup4

# Install system packages
RUN apt-get update && apt-get install -y \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# Install Node.js packages globally
RUN npm install -g some-mcp-package
```

--------------------------------

### Clone MetaMCP Repository

Source: https://docs.metamcp.com/en/development

Clone the MetaMCP repository locally to begin development. Ensure you have Git installed and have forked the repository on GitHub.

```bash
git clone https://github.com/YOUR_USERNAME/metamcp.git
cd metamcp
```

--------------------------------

### AI Translation Prompt Example

Source: https://docs.metamcp.com/en/development/i18n

Use this prompt structure when asking AI tools to translate JSON files, ensuring structure and key preservation.

```prompt
Translate this English JSON file to Spanish, maintaining the same structure and keys:

{
  "server": {
    "create": "Create Server",
    "edit": "Edit Server"
  }
}

Keep technical terms like "MCP" and "API" unchanged.
```

--------------------------------

### Remote MetaMCP Production Setup

Source: https://docs.metamcp.com/en/integrations/claude-desktop

Configure Claude Desktop to connect to a remote MetaMCP instance in production using mcp-proxy, Streamable HTTP, and API key authentication.

```json
{
  "mcpServers": {
    "MetaMCP-Production": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "https://your-metamcp-domain.com/metamcp/your-endpoint-name/mcp"
      ],
      "env": {
        "API_ACCESS_TOKEN": "sk_mt_production_key"
      }
    }
  }
}
```

--------------------------------

### SSE Server with Custom Headers

Source: https://docs.metamcp.com/en/concepts/mcp-servers

Example of adding custom HTTP headers to an SSE server configuration, useful for additional authentication or metadata.

```json
{
  "type": "SSE",
  "url": "https://api.example.com/sse",
  "headers": {
    "X-API-Key": "your-api-key",
    "X-API-Version": "v2",
    "Organization-ID": "org-123"
  }
}
```

--------------------------------

### mcp.json Setup for Multiple MetaMCP Endpoints

Source: https://docs.metamcp.com/en/integrations/cursor

Configure mcp.json to connect to multiple MetaMCP endpoints, each with its own URL and authentication.

```json
{
  "mcpServers": {
    "MetaMCP-Dev": {
      "url": "http://localhost:12008/metamcp/dev-tools/mcp",
      "headers": {
        "Authorization": "Bearer sk_mt_dev_key"
      }
    },
    "MetaMCP-Research": {
      "url": "http://localhost:12008/metamcp/research-tools/mcp",
      "headers": {
        "Authorization": "Bearer sk_mt_research_key"
      }
    }
  }
}
```

--------------------------------

### Configure APP_URL for MetaMCP

Source: https://docs.metamcp.com/en/integrations/open-web-ui

Set the APP_URL environment variable in the .env file to ensure Open WebUI can reach your MetaMCP instance. This is crucial for both local and deployed setups.

```bash
# For local Open WebUI accessing local MetaMCP
APP_URL=http://localhost:12008

# For deployed Open WebUI accessing deployed MetaMCP
APP_URL=https://your-metamcp-domain.com

# For local Open WebUI accessing deployed MetaMCP
APP_URL=https://your-metamcp-domain.com
```

```bash
POSTGRES_PASSWORD=your_secure_password
BETTER_AUTH_SECRET=your_auth_secret  # Generate with: openssl rand -hex 32 | base64
```

--------------------------------

### Metamcp Tool Listing Sequence Diagram

Source: https://docs.metamcp.com/en/development/architecture

Illustrates the sequence of requests and responses between MCP Client, MetaMCP Server, and Installed MCP Servers for listing available tools. This flow is used to discover and aggregate tool capabilities.

```mermaid
sequenceDiagram
    participant MCPClient as MCP Client (e.g., Claude Desktop)
    participant MetaMCP as MetaMCP Server
    participant MCPServers as Installed MCP Servers

    MCPClient ->> MetaMCP: Request list tools

    loop For each listed MCP Server
        MetaMCP ->> MCPServers: Request list_tools
        MCPServers ->> MetaMCP: Return list of tools
    end

    MetaMCP ->> MetaMCP: Aggregate tool lists & apply middleware
    MetaMCP ->> MCPClient: Return aggregated list of tools

    MCPClient ->> MetaMCP: Call tool
    MetaMCP ->> MCPServers: call_tool to target MCP Server
    MCPServers ->> MetaMCP: Return tool response
    MetaMCP ->> MCPClient: Return tool response
```

--------------------------------

### Get Endpoint Configuration with Authentication

Source: https://docs.metamcp.com/en/troubleshooting/oauth-troubleshooting

Use this curl command to fetch the configuration of an endpoint. This is helpful for verifying authentication settings and ownership.

```bash
# Get endpoint configuration
curl -H "Authorization: Bearer your-token" \
  https://your-domain.com/api/endpoints/endpoint-uuid
```

--------------------------------

### Translate Common JSON Content

Source: https://docs.metamcp.com/en/development/i18n

Example of translating the 'common.json' file into Spanish. Modify the values for each key to provide the correct translation.

```json
// public/locales/es/common.json
{
  "actions": {
    "save": "Guardar",
    "cancel": "Cancelar",
    "delete": "Eliminar",
    "edit": "Editar",
    "create": "Crear"
  }
}
```

--------------------------------

### Both API Key and OAuth Enabled - Valid OAuth Token

Source: https://docs.metamcp.com/en/troubleshooting/oauth-troubleshooting

Example of a valid request using an OAuth bearer token when both API key and OAuth authentication are enabled. This is used if no API key is provided.

```bash
curl -H "Authorization: Bearer mcp_token_1234567890abcdef" \
  https://your-domain.com/api/endpoint
```

--------------------------------

### Get Endpoint Details with Authentication

Source: https://docs.metamcp.com/en/troubleshooting/oauth-troubleshooting

Use this curl command to retrieve details about a specific endpoint. Ensure you include the correct Authorization header for authentication.

```bash
# Get endpoint details
curl -H "Authorization: Bearer your-token" \
  https://your-domain.com/api/endpoints/endpoint-uuid
```

--------------------------------

### Run Database Migrations

Source: https://docs.metamcp.com/en/development/contributing

Execute development database migrations after setting up the `.env.local` file.

```bash
cd apps/backend

pnpm db:migrate:dev
```

--------------------------------

### Configure Firewall

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Set up the Uncomplicated Firewall (UFW) to allow SSH, Nginx traffic, and then enable the firewall.

```bash
ufw allow OpenSSH
ufw allow 'Nginx Full'
ufw enable
```

--------------------------------

### Run Database Migrations

Source: https://docs.metamcp.com/en/development

Apply database migrations to set up the database schema. Ensure your `.env.local` file is configured correctly before running this command in the backend directory.

```bash
cd apps/backend
pnpm db:migrate:dev
```

--------------------------------

### Build and Run with Docker

Source: https://docs.metamcp.com/en/development

Build the Docker images and run the application using Docker Compose. This is useful for testing the application in a production-like environment.

```bash
docker compose build
```

```bash
docker compose up
```

--------------------------------

### STDIO Server Authentication with API Key

Source: https://docs.metamcp.com/en/concepts/mcp-servers

Shows how to configure authentication for a STDIO server using an API key passed via environment variables.

```json
{
    "env": {
      "API_KEY": "your-secret-key"
    }
  }
```

--------------------------------

### Create Documentation Branch

Source: https://docs.metamcp.com/en/development/contributing

Create a new branch for making documentation updates.

```bash
git checkout -b docs/documentation-update
```

--------------------------------

### Add shadcn/ui Components

Source: https://docs.metamcp.com/en/development

Command to add new shadcn/ui components to the frontend application. Navigate to the frontend directory before running the command.

```bash
# Add new components
cd apps/frontend
npx shadcn-ui@latest add [component-name]
```

--------------------------------

### Create a Namespace for MCP Servers

Source: https://docs.metamcp.com/en/quickstart

Group multiple MCP servers into a namespace to provide a unified endpoint. Assign a name, description, and select the desired MCP servers.

```bash
news-information
```

--------------------------------

### STDIO Server with Environment Variable Interpolation

Source: https://docs.metamcp.com/en/concepts/mcp-servers

Demonstrates using environment variable interpolation `${ENV_VAR}` within the 'env' section for dynamic configuration of STDIO servers.

```json
{
  "name": "ExampleServer",
  "type": "STDIO",
  "command": "uvx",
  "args": ["mcp-example"],
  "env": {
    "API_KEY": "${API_KEY}",
    "DEBUG": "true"
  }
}
```

--------------------------------

### Create Nginx Site Configuration

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Create a new Nginx site configuration file for your domain. This includes settings for both HTTP (redirect to HTTPS) and HTTPS (with SSL configuration).

```bash
sudo nano /etc/nginx/sites-available/metamcp
```

```nginx
server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name yourdomain.com;

    # SSL configuration (will be managed by Certbot)
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;

    location / {
        proxy_pass http://localhost:12008;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # SSE-specific optimizations for MCP connections
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;  # 24 hours for long-lived SSE connections
        proxy_send_timeout 86400s;
        
        # HTTP/1.1 with proper connection handling for SSE
        proxy_set_header Connection '';
        proxy_http_version 1.1;
        
        # Additional headers for better SSE support
        proxy_set_header Cache-Control 'no-cache';
        proxy_set_header X-Accel-Buffering 'no';
    }

    # Optional: Increase client max body size for file uploads
    client_max_body_size 100M;
}
```

--------------------------------

### Clone MetaMCP Repository

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Clone the MetaMCP repository into the /opt directory and change ownership to the current user. Then, navigate into the cloned directory.

```bash
cd /opt
sudo git clone https://github.com/metatool-ai/metamcp.git
sudo chown -R $USER:$USER metamcp
cd metamcp
```

--------------------------------

### Add a MCP Server Configuration

Source: https://docs.metamcp.com/en/quickstart

Configure a new MCP server, specifying its name, description, type, command, arguments, and environment variables. You can set it as private or public.

```bash
mcp-hn
```

--------------------------------

### Define a Development Namespace Configuration

Source: https://docs.metamcp.com/en/concepts/namespaces

This JSON defines a namespace named 'development-tools' that includes filesystem and git-helper servers, each with their active tools. Use this structure to configure your namespaces.

```json
{
  "name": "development-tools",
  "description": "Essential development tools",
  "servers": [
    {
      "name": "filesystem",
      "status": "ACTIVE",
      "tools": ["read_file", "write_file", "list_directory"]
    },
    {
      "name": "git-helper", 
      "status": "ACTIVE",
      "tools": ["git_status", "git_commit", "git_diff"]
    }
  ]
}
```

--------------------------------

### Configure OIDC Environment Variables

Source: https://docs.metamcp.com/en/development

Set these environment variables to configure the OpenID Connect provider for enterprise SSO. Ensure client ID, secret, and discovery URL are correctly set.

```bash
# Required
OIDC_CLIENT_ID=your-oidc-client-id
OIDC_CLIENT_SECRET=your-oidc-client-secret
OIDC_DISCOVERY_URL=https://your-provider.com/.well-known/openid-configuration
OIDC_AUTHORIZATION_URL=https://your-provider.com/auth/authorize

# Optional
OIDC_PROVIDER_ID=oidc
OIDC_SCOPES=openid email profile
OIDC_PKCE=true
```

--------------------------------

### STDIO Server Configuration

Source: https://docs.metamcp.com/en/concepts/mcp-servers

Configuration for a STDIO type MCP server, including command, arguments, and environment variables.

```json
{
      "type": "STDIO",
      "command": "uvx", 
      "args": ["mcp-server-package"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
```

--------------------------------

### Connect to VPS via SSH

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Connect to your newly created DigitalOcean VPS using SSH. Replace 'your_server_ip' with the actual IP address of your droplet.

```bash
ssh root@your_server_ip
```

--------------------------------

### Add Docker GPG Key and Repository

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Add Docker's official GPG key to ensure package authenticity and configure the Docker APT repository for your Ubuntu version.

```bash
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
```

--------------------------------

### Create Temporary HTTP-Only Nginx Configuration

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Create a temporary Nginx configuration file that only listens on port 80. This is used to initially obtain an SSL certificate with Let's Encrypt.

```bash
# Create temporary HTTP-only config
sudo nano /etc/nginx/sites-available/metamcp-temp
```

```nginx
server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:12008;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

--------------------------------

### Configure Multiple MetaMCP Endpoints

Source: https://docs.metamcp.com/en/integrations/claude-desktop

Set up Claude Desktop to connect to multiple MetaMCP endpoints, each with its own configuration for Streamable HTTP or SSE, and distinct API keys.

```json
{
  "mcpServers": {
    "MetaMCP-Dev": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "http://localhost:12008/metamcp/dev-tools/mcp"
      ],
      "env": {
        "API_ACCESS_TOKEN": "sk_mt_dev_key"
      }
    },
    "MetaMCP-Research": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "http://localhost:12008/metamcp/research-tools/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "sk_mt_research_key"
      }
    }
  }
}
```

--------------------------------

### Enable API Key and OAuth Authentication

Source: https://docs.metamcp.com/en/troubleshooting/oauth-troubleshooting

Configure endpoint settings to allow both API key and OAuth authentication. This is useful when migrating or supporting multiple authentication methods.

```json
{
  "enable_api_key_auth": true,
  "enable_oauth": true
}
```

--------------------------------

### Enable Temporary Nginx Config and Obtain SSL Certificate

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Enable the temporary HTTP-only Nginx configuration and reload Nginx. Then, use Certbot to obtain an SSL certificate for your domain.

```bash
sudo ln -sf /etc/nginx/sites-available/metamcp-temp /etc/nginx/sites-enabled/metamcp
sudo nginx -t && sudo systemctl reload nginx
```

```bash
sudo certbot --nginx -d yourdomain.com
```

--------------------------------

### Copy English Translation Files

Source: https://docs.metamcp.com/en/development/i18n

Copies all existing English translation files to the new language directory as a template. This ensures all keys are present before translation.

```bash
cp -r public/locales/en/* public/locales/es/
```

--------------------------------

### STDIO Server Import Format

Source: https://docs.metamcp.com/en/concepts/mcp-servers

JSON format for importing a single STDIO MCP server configuration. Ensure the 'type' is set to 'stdio'.

```json
{
  "mcpServers": {
    "ServerName": {
      "type": "stdio",
      "command": "uvx",
      "args": ["package-name"],
      "env": {
        "API_KEY": "your-key"
      },
      "description": "Optional description"
    }
  }
}
```

--------------------------------

### Database Migration Commands

Source: https://docs.metamcp.com/en/development

Commands for managing database schema migrations. Use `db:generate` after schema changes, `db:migrate:dev` to apply them, and `db:reset` for development environments.

```bash
# Generate migration after schema changes
cd apps/backend
pnpm db:generate

# Apply migrations
pnpm db:migrate:dev # which uses env.local for PG related env vars

# Reset database (development only)
pnpm db:reset
```

--------------------------------

### Create Language Directory

Source: https://docs.metamcp.com/en/development/i18n

Command to create a new directory for a specific language, such as Spanish ('es'), within the public locales directory. This is the first step in adding a new language.

```bash
mkdir -p public/locales/es  # For Spanish
```

--------------------------------

### Streamable HTTP Server Configuration

Source: https://docs.metamcp.com/en/concepts/mcp-servers

Configuration for a Streamable HTTP MCP server, including URL, bearer token, and custom headers.

```json
{
      "type": "STREAMABLE_HTTP",
      "url": "https://api.example.com/mcp",
      "bearerToken": "your-bearer-token",
      "headers": {
        "X-Custom-Header": "value"
      }
    }
```

--------------------------------

### Clone MetaMCP Repository

Source: https://docs.metamcp.com/en/development/contributing

Clone your forked repository locally and set up the upstream remote to track changes from the main project.

```bash
git clone https://github.com/YOUR_USERNAME/metamcp.git
cd metamcp

```

```bash
git remote add upstream https://github.com/metatool-ai/metamcp.git
```

--------------------------------

### Configure Streamable HTTP for MetaMCP

Source: https://docs.metamcp.com/en/integrations/claude-desktop

Use this JSON configuration to connect Claude Desktop to a MetaMCP endpoint via Streamable HTTP using mcp-proxy. Ensure API key authentication is set up correctly.

```json
{
  "mcpServers": {
    "MetaMCP": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "http://localhost:12008/metamcp/your-endpoint-name/mcp"
      ],
      "env": {
        "API_ACCESS_TOKEN": "sk_mt_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Streamable HTTP Server Import Format

Source: https://docs.metamcp.com/en/concepts/mcp-servers

JSON format for importing a single Streamable HTTP MCP server configuration. This is used for servers accessible via HTTP.

```json
{
  "mcpServers": {
    "ServerName": {
      "type": "streamable_http",
      "url": "https://api.example.com/mcp",
      "bearerToken": "your-token",
      "headers": {
        "X-Custom-Header": "value"
      },
      "description": "Optional description"
    }
  }
}
```

--------------------------------

### SSE Server Import Format

Source: https://docs.metamcp.com/en/concepts/mcp-servers

JSON format for importing a single SSE MCP server configuration. Use this when the server uses Server-Sent Events.

```json
{
  "mcpServers": {
    "ServerName": {
      "type": "sse",
      "url": "https://api.example.com/sse",
      "bearerToken": "your-token",
      "headers": {
        "X-Custom-Header": "value"
      },
      "description": "Optional description"
    }
  }
}
```

--------------------------------

### Create Feature Branch

Source: https://docs.metamcp.com/en/development

Create a new branch for developing a feature. While naming is not strictly required, using a descriptive name like `feature/your-feature-name` is recommended.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Verify Docker Service Status

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Check if the Docker service is running correctly on your system.

```bash
sudo systemctl status docker
```

--------------------------------

### Lint and Fix Code Quality Issues

Source: https://docs.metamcp.com/en/development

Run ESLint to check for code quality issues and Prettier for formatting. Use `pnpm lint:fix` to automatically fix most linting problems.

```bash
pnpm lint
```

```bash
pnpm lint:fix
```

--------------------------------

### Remote Server Authentication with Bearer Token

Source: https://docs.metamcp.com/en/concepts/mcp-servers

Illustrates configuring authentication for SSE or Streamable HTTP servers using a bearer token.

```json
{
    "bearerToken": "your-bearer-token"
  }
```

--------------------------------

### Both API Key and OAuth Enabled - No Token Provided

Source: https://docs.metamcp.com/en/troubleshooting/oauth-troubleshooting

When neither an API key nor an OAuth token is provided, and both authentication methods are enabled, this response indicates that authentication is required.

```json
{
  "error": "authentication_required",
  "error_description": "Authentication required via OAuth bearer token or API key",
  "supported_methods": [
    "Authorization header (Bearer token)",
    "X-API-Key header",
    "query parameter (api_key or apikey)"
  ]
}
```

--------------------------------

### Optional Fields for MCP Server Configuration

Source: https://docs.metamcp.com/en/concepts/mcp-servers

Lists optional fields that can be included in an MCP server configuration to provide descriptions, environment variables, authentication tokens, and custom headers.

```json
{
    "description": "Human-readable description",
    "env": {
      "KEY": "value"
    },
    "bearerToken": "auth-token",  
    "headers": {
      "X-Custom-Header": "value"
    }
  }
```

--------------------------------

### Endpoint URL Formats

Source: https://docs.metamcp.com/en/concepts/endpoints

These are the standard URL path formats for accessing an endpoint. The '{name}' placeholder should be replaced with the specific name of your endpoint.

```text
/metamcp/{name}/sse
```

```text
/metamcp/{name}/mcp
```

```text
/metamcp/{name}/api
```

```text
/metamcp/{name}/api/openapi.json
```

--------------------------------

### Configure SSE for MetaMCP

Source: https://docs.metamcp.com/en/integrations/claude-desktop

This JSON configuration enables Claude Desktop to connect to a MetaMCP endpoint using SSE (Server-Sent Events) via mcp-proxy. It includes API key authentication.

```json
{
  "mcpServers": {
    "MetaMCP": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "http://localhost:12008/metamcp/your-endpoint-name/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "sk_mt_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### API Key Authentication Configuration

Source: https://docs.metamcp.com/en/integrations/cursor

Configure API key authentication for MetaMCP by providing an Authorization header.

```json
{
  "mcpServers": {
    "MetaMCP": {
      "url": "http://localhost:12008/metamcp/your-endpoint-name/mcp",
      "headers": {
        "Authorization": "Bearer sk_mt_your_key_here"
      }
    }
  }
}
```

--------------------------------

### No Authentication for Public MetaMCP Endpoints

Source: https://docs.metamcp.com/en/integrations/claude-desktop

Connect Claude Desktop to public MetaMCP endpoints using mcp-proxy without requiring an API key, suitable for unauthenticated SSE connections.

```json
{
  "mcpServers": {
    "MetaMCP": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "http://localhost:12008/metamcp/public-tools/sse"
      ]
    }
  }
}
```

--------------------------------

### Debug Mode Configuration

Source: https://docs.metamcp.com/en/integrations/general-stdio-with-api-key

Enable debug logging for mcp-proxy to troubleshoot connection or authentication issues. This will provide more verbose output.

```json
{
  "mcpServers": {
    "MetaMCP": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "--debug",
        "http://localhost:12008/metamcp/your-endpoint-name/mcp"
      ],
      "env": {
        "API_ACCESS_TOKEN": "sk_mt_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Set Up Auto-Renewal for SSL Certificate

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Test the auto-renewal process for the SSL certificate using Certbot's dry run command. Then, add a cron job to ensure the certificate is renewed automatically.

```bash
# Test auto-renewal
sudo certbot renew --dry-run
```

```bash
# Add to crontab for automatic renewal
sudo crontab -e
```

```cron
0 12 * * * /usr/bin/certbot renew --quiet
```

--------------------------------

### Basic OAuth Configuration with mcp-remote

Source: https://docs.metamcp.com/en/integrations/general-stdio-with-oauth

Use this JSON configuration to set up a single MetaMCP endpoint with OAuth authentication via mcp-remote. Ensure 'your-endpoint-name' is replaced with your actual endpoint name.

```json
{
  "mcpServers": {
    "MetaMCP": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:12008/metamcp/your-endpoint-name/mcp"
      ]
    }
  }
}
```

--------------------------------

### Public Endpoint - No Authentication Required

Source: https://docs.metamcp.com/en/troubleshooting/oauth-troubleshooting

Use this configuration when no authentication is needed for requests. No authentication headers are required.

```json
{
  "message": "Public endpoint - no authentication required"
}
```

--------------------------------

### Create Bug Fix Branch

Source: https://docs.metamcp.com/en/development/contributing

Create a new branch for addressing a bug fix.

```bash
git checkout -b fix/issue-description
```

--------------------------------

### Exported MCP Server Configurations

Source: https://docs.metamcp.com/en/concepts/mcp-servers

This JSON structure represents the format for exporting MCP server configurations. It includes details for different server types like stdio, sse, and streamable_http.

```json
{
  "mcpServers": {
    "HackerNews": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-hn"],
      "description": "Access HackerNews stories and comments"
    },
    "TimeServer": {
      "type": "stdio", 
      "command": "uvx",
      "args": ["mcp-server-time"],
      "env": {
        "TZ": "America/New_York"
      },
      "description": "Time and timezone utilities"
    },
    "RemoteAPI": {
      "type": "streamable_http",
      "url": "https://api.example.com/mcp",
      "bearerToken": "your-bearer-token",
      "headers": {
        "X-API-Version": "v2"
      },
      "description": "Remote MCP server via HTTP"
    }
  }
}
```

--------------------------------

### No Authentication Configuration for Public Endpoints

Source: https://docs.metamcp.com/en/integrations/cursor

Configure MetaMCP for public endpoints where no authentication is required.

```json
{
  "mcpServers": {
    "MetaMCP": {
      "url": "http://localhost:12008/metamcp/public-tools/sse"
    }
  }
}
```

--------------------------------

### Bug Report Template

Source: https://docs.metamcp.com/en/development

A template for reporting bugs, including sections for description, steps to reproduce, environment details, and additional context. This helps maintainers understand and resolve issues effectively.

```markdown
## Bug Description
Brief description of the issue

## Steps to Reproduce
1. Step one
2. Step two
3. Expected vs actual behavior

## Environment
- OS: [e.g., macOS 14.0]
- Browser: [e.g., Chrome 120]
- MetaMCP Version: [e.g., 1.0.0]

## Additional Context
Screenshots, logs, or other relevant information
```

--------------------------------

### API Key Authentication - Valid Request

Source: https://docs.metamcp.com/en/troubleshooting/oauth-troubleshooting

Requires a valid API key via the X-API-Key header or query parameter. This is used when API key authentication is enabled and OAuth is disabled.

```bash
curl -H "X-API-Key: mcp_1234567890abcdef" \
  https://your-domain.com/api/endpoint
```

--------------------------------

### SSE Server Configuration

Source: https://docs.metamcp.com/en/concepts/mcp-servers

Configuration for a Server-Sent Events (SSE) MCP server, specifying the URL, bearer token, and custom headers.

```json
{
      "type": "SSE",
      "url": "https://api.example.com/sse",
      "bearerToken": "your-bearer-token",
      "headers": {
        "X-Custom-Header": "value"
      }
    }
```

--------------------------------

### Required Fields for MCP Server Configuration

Source: https://docs.metamcp.com/en/concepts/mcp-servers

Defines the essential fields required for any MCP server configuration, including name, type, and server-specific details like command/URL.

```json
{
    "name": "unique-server-name",
    "type": "STDIO|SSE|STREAMABLE_HTTP",
    "command": "command-to-run", 
    "args": ["arg1", "arg2"],     
    "url": "https://...",         
  }
```

--------------------------------

### SSE Transport Configuration for MetaMCP

Source: https://docs.metamcp.com/en/integrations/cursor

Configure MetaMCP to use Server-Sent Events (SSE) as an alternative transport protocol.

```json
{
  "mcpServers": {
    "MetaMCP": {
      "url": "http://localhost:12008/metamcp/your-endpoint-name/sse"
    }
  }
}
```

--------------------------------

### API Key Authentication - Invalid/Missing Key Response

Source: https://docs.metamcp.com/en/troubleshooting/oauth-troubleshooting

Response when the API key is missing or invalid. This configuration requires API key authentication.

```json
{
  "error": "authentication_required",
  "error_description": "Authentication required via API key",
  "supported_methods": [
    "X-API-Key header",
    "query parameter (api_key or apikey)"
  ],
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

--------------------------------

### API Key Authentication for MetaMCP Proxy

Source: https://docs.metamcp.com/en/integrations/claude-desktop

Configure mcp-proxy with an API access token for secure connection to MetaMCP endpoints using Streamable HTTP.

```json
{
  "mcpServers": {
    "MetaMCP": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "http://localhost:12008/metamcp/your-endpoint-name/mcp"
      ],
      "env": {
        "API_ACCESS_TOKEN": "sk_mt_your_key_here"
      }
    }
  }
}
```

--------------------------------

### Authentication Translations

Source: https://docs.metamcp.com/en/development/i18n

Contains translations for authentication-related text, such as sign-in, sign-up, and password fields. Use this for all auth UI components.

```json
{
  "signIn": "Sign In",
  "signOut": "Sign Out",
  "signUp": "Sign Up",
  "email": "Email",
  "password": "Password",
  "forgotPassword": "Forgot Password?",
  "createAccount": "Create Account",
  "loginWithOIDC": "Login with OIDC"
}
```

--------------------------------

### Add User to Docker Group

Source: https://docs.metamcp.com/en/deployment/custom-deployment

Add the current user to the 'docker' group to allow running Docker commands without sudo. Log out and back in or use 'newgrp docker' for changes to take effect.

```bash
sudo usermod -aG docker $USER
```

```bash
newgrp docker
```

--------------------------------

### Restore Full Nginx Configuration After SSL

Source: https://docs.metamcp.com/en/deployment/custom-deployment

After obtaining the SSL certificate, restore the original, full Nginx configuration that includes both HTTP and HTTPS settings. Test and reload Nginx.

```bash
sudo ln -sf /etc/nginx/sites-available/metamcp /etc/nginx/sites-enabled/metamcp
sudo nginx -t && sudo systemctl reload nginx
```