MCP Server Setup Guide¶

Startup Procedure¶

1. Environment Variable Configuration¶

Copy .env.example to .env and edit as needed.

cp .env.example .env

2. Start Docker Containers¶

docker compose up -d

On first startup, the image will be built and the database will be initialized.

3. Check Logs¶

docker compose logs -f web

Once startup is complete, the default administrator's Bearer token will be displayed in the logs.

4. Access Web Admin Interface¶

Open https://localhost/ in your browser (no port number). Caddy reverse-proxies ports 80/443; the app's port 5000 itself is not published to the host, so :5000 will not work. You'll see a self-signed certificate warning — choose "Advanced" → "Proceed" to continue (see Scaling & Containers if you want to remove the warning).

If you started directly with python run.py (no Docker), use http://localhost:5000/ instead.

Default Administrator Account:

Login ID: admin
Password: admin

Note: The admin UI is routed by path, so https://localhost/, https://lvh.me/, and https://admin.lvh.me/ all show the same screen. Only MCP services are distinguished by subdomain.

Basic Usage¶

1. Service Registration¶

Click "Service Management" from the dashboard
Click "New Service Registration"
Enter the following:
Service Name: Any name
Subdomain: Connection path for MCP clients (e.g., myservice)
Common Headers: Headers used by all Capabilities (JSON format)

Subdomain Example:

Subdomain: myservice
→ MCP Endpoint: https://myservice.lvh.me/mcp   (Docker Compose, via Caddy)
→ MCP Endpoint: http://myservice.lvh.me:5000/mcp  (when run directly with python run.py)

2. Capability Registration¶

Click "Capabilities Management" from the service details screen
Click "New Capability Registration"
Enter the following:
Capability Name: Name displayed as MCP Tool
Connection Type: API or MCP
Connection URL: URL of the relay destination API/MCP server
Header Parameters: Individual header settings
Body Parameters: Default parameters

API Capability Example:

Capability Name: get_weather
Connection Type: API
Connection URL: https://api.weather.com/v1/current
Header Parameters:
  X-API-Key: your-api-key
Body Parameters:
  units: metric

MCP Capability Example:

Capability Name: search_database
Connection Type: MCP
Connection URL: http://other-mcp-server:5000/mcp/db

3. User Registration¶

Click "Account Management" from the dashboard
Click "New Account Registration"
Enter login ID and password, then register
After registration, check the Bearer token on the account details screen

4. Permission Setup¶

On the account details screen, click "Add Permission"
Select service and capability
Click "Add"

Now the account can use the specified capability.

Connecting from MCP Clients¶

The URLs below are for Docker Compose (via Caddy, https://, no port number). If you started directly with python run.py (no Docker), use http:// + :5000 instead.

Subdomain-Based Access (Recommended)¶

Using lvh.me Domain¶

lvh.me is a public domain for local development that always resolves to 127.0.0.1.

# Get Capabilities (curl needs -k since the cert is self-signed)
curl -k -H "Authorization: Bearer YOUR_TOKEN" \
  https://myservice.lvh.me/mcp

# Execute Tool
curl -k -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"param": "value"}}' \
  https://myservice.lvh.me/tools/get_weather

Using Query Parameters¶

curl -k -H "Authorization: Bearer YOUR_TOKEN" \
  https://localhost/mcp?subdomain=myservice

MCP Client Configuration Examples¶

Dify¶

{
  "mcp_servers": {
    "my_service": {
      "url": "https://myservice.lvh.me/mcp",
      "auth": {
        "type": "bearer",
        "token": "YOUR_BEARER_TOKEN"
      }
    }
  }
}

Claude Desktop¶

{
  "mcpServers": {
    "my-service": {
      "url": "https://myservice.lvh.me/mcp",
      "transport": {
        "type": "http"
      },
      "headers": {
        "Authorization": "Bearer YOUR_BEARER_TOKEN"
      }
    }
  }
}

Legacy Endpoint (Backward Compatibility)¶

{
  "mcpServers": {
    "my-service": {
      "url": "https://localhost/mcp/myservice",
      "headers": {
        "Authorization": "Bearer YOUR_BEARER_TOKEN"
      }
    }
  }
}

stdio Connection¶

{
  "mcpServers": {
    "my-service": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "mcp_server",
        "python",
        "stdio_server.py",
        "myservice",
        "<User's Bearer Token>"
      ]
    }
  }
}

Use Cases¶

1. External API Relay¶

Example of using a weather API via MCP:

Register Service:
Name: Weather Service
Subdomain: weather
Register Capability:
Name: get_current_weather
Type: API
URL: https://api.openweathermap.org/data/2.5/weather
Headers: appid: YOUR_API_KEY
Body Parameters: units: metric
Grant permission to account
From MCP client:

User: Tell me the weather in Tokyo
AI: (Uses get_current_weather tool to retrieve weather information)

2. Integrating Multiple MCP Servers¶

Example of integrating database MCP server and filesystem MCP server:

Register Service: Integration Hub
Register Capabilities:
database_query (MCP, http://db-mcp:5000/mcp/db)
file_read (MCP, http://fs-mcp:5002/mcp/files)
Grant only necessary capabilities per account

Troubleshooting¶

Database Connection Error¶

# Check MySQL container logs
docker compose logs db

# Wait for database to start
docker compose restart web

Port Conflict¶

Only the caddy service's ports 80/443 are published to the host (web/mcp port 5000 is internal-only). If 80/443 conflict with something else, change the caddy service's ports in compose.yaml:

ports:
  - "8080:80"
  - "8443:443"

Certificate warning on `https://localhost/`¶

This is expected: Caddy issues a self-signed certificate automatically for local development. See Scaling & Containers for details.

Invalid Token¶

Click "Regenerate Token" on the account details screen to issue a new token.

Security¶

Production Environment Settings¶

Change SECRET_KEY

# .env file
SECRET_KEY=random-long-string

Change Administrator Password
After login, change password on the account details screen
Use HTTPS
SSL/TLS termination with reverse proxy (Nginx, Traefik)
Change Database Password
Change MYSQL_PASSWORD etc. in compose.yaml

Data Backup¶

# Backup database
docker compose exec db mysqldump -u mcpuser -pmcppassword mcpdb > backup.sql

# Restore database
docker compose exec -T db mysql -u mcpuser -pmcppassword mcpdb < backup.sql

Development Mode¶

For local development:

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start development server
export DATABASE_URL=mysql+pymysql://mcpuser:mcppassword@localhost:3306/mcpdb
python run.py

API Reference¶

Service API¶

GET /api/services - Service list
POST /api/services - Create service
GET /api/services/{id} - Service details
PUT /api/services/{id} - Update service
DELETE /api/services/{id} - Delete service

Capability API¶

GET /api/services/{id}/capabilities - Capability list
POST /api/services/{id}/capabilities - Create capability
GET /api/capabilities/{id} - Capability details
PUT /api/capabilities/{id} - Update capability
DELETE /api/capabilities/{id} - Delete capability

Account API¶

GET /api/users - Account list
POST /api/users - Create account
GET /api/users/{id} - Account details
PUT /api/users/{id} - Update account
DELETE /api/users/{id} - Delete account
POST /api/users/{id}/regenerate_token - Regenerate token

Permission API¶

GET /api/users/{id}/permissions - Account permission list
POST /api/users/{id}/permissions - Add permission
DELETE /api/permissions/{id} - Delete permission

MCP API¶

POST /mcp/{subdomain} - MCP request processing
Authorization: Bearer {token}
Content-Type: application/json