Public API MCP Server

An MCP (Model Context Protocol) server that dynamically exposes a public API defined by an OpenAPI 3 specification.

Quick Start

Development (Stdio Mode)

# One-liner to add dev server (with hot reload)
claude mcp add --transport stdio ampeco-api-dev \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- bash -c "cd /absolute/path/to/public-api-mcp && npm run dev:stdio"

Production (via NPX)

# One-liner to add production server
claude mcp add --transport stdio ampeco-api \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- npx -y @ampeco/public-api-mcp --stdio --hostname https://api.example.com

HTTP Mode (Remote Server)

# Start the server first
PORT=3001 npm run dev:http

# Then add to Claude Code
claude mcp add --transport http ampeco-api \
  http://localhost:3001/api.example.com \
  --header "Authorization: Bearer your-token-here"

See Setting Up with Claude Code for detailed instructions and troubleshooting.

Overview

This project transforms OpenAPI specifications into optimized, self-contained API definitions that can be served through the Model Context Protocol. It features a sophisticated build pipeline that processes OpenAPI specs at build time to minimize runtime overhead and reduce token usage.

Usage

Running the Build Pipeline

# Install dependencies
npm install

# Run the build pipeline with default path
npm run build

# Run the build pipeline with custom OpenAPI spec path
OPENAPI_SPEC_PATH=/path/to/your/openapi.yaml npm run build

# Or set it as an environment variable for multiple commands
export OPENAPI_SPEC_PATH=/path/to/your/openapi.yaml
npm run build
npm run dev

The build script:

Parses the OpenAPI spec from the specified path
Processes all endpoints through the optimization pipeline
Generates Zod schemas for runtime validation
Outputs optimized artifacts to src/generated/

Configuration Options:

OPENAPI_SPEC_PATH: Path to the OpenAPI YAML/JSON file (relative or absolute)
- Can be set as an environment variable or passed directly to npm commands
- Used by both npm run build and npm run dev

Development

# Type check without building
npm run type-check

# Run in development mode (build + start server)
npm run dev

Architecture

Build-Time Pipeline

OpenAPI Spec
    ↓
[Parser] Bundle & Resolve References
    ↓
[Extractor] Extract Endpoints & Security
    ↓
[Flattener] Flatten Schemas (allOf, nested objects)
    ↓
[Optimizer] Minify & Optimize
    ↓
[Zod Generator] Generate Validation Schemas
    ↓
Generated Artifacts (endpoints.json, schemas.ts)

MCP Server

The server provides a complete MCP implementation for accessing your OpenAPI-defined API:

Dual Transport Support: Both Stdio (local) and HTTP (remote) transports
Flexible Resource Mode: Native MCP resources OR tool-based emulation for Claude Desktop compatibility
Dynamic Resources: All API endpoints exposed as MCP resources with full schema details
API Request Tool: Fully typed api_request tool with automatic authentication and parameter validation
Stateless Architecture: No session state required - all parameters provided per request
Zero Configuration: Pre-processed data loads instantly, no config files needed
MCP Protocol Compliance: Full implementation of MCP Streamable HTTP transport specification

Resource Modes

The server supports two modes for exposing API endpoints:

Native Resources Mode (Default): Uses native MCP resources for endpoint discovery
- Best for: MCP clients that fully support the resources capability
- Features: Hierarchical 3-tier navigation (tags → endpoints → details)
Tool Emulation Mode: Exposes resources through tools (list_resources, read_resource)
- Required for Claude Desktop (does not support native MCP resources)
- Provides identical functionality through tool-based interface
- Enable with --emulate-resources-via-tools flag

Running the Server

# Development mode (rebuild + start server)
npm run dev

# Production mode
npm run build  # First time only
npm start

# Custom port
PORT=3001 npm run dev

Server Endpoints

The server uses a hostname-based routing structure where the target API hostname is embedded in the URL path:

GET /health: Health check and server statistics
POST /{hostname}[/{protocol}]: MCP protocol endpoint with hostname routing
- {hostname}: Target API hostname (e.g., api.example.com)
- {protocol}: Optional protocol (http or https, defaults to https)

Examples:

POST /api.example.com → Routes to https://api.example.com
POST /api.example.com/https → Routes to https://api.example.com
POST /api.example.com/http → Routes to http://api.example.com
POST /internal.api.company.com/http → Routes to http://internal.api.company.com

Setting Up with Claude Desktop

IMPORTANT: Claude Desktop does not support native MCP resources. You MUST use the --emulate-resources-via-tools flag for Claude Desktop.

Installation via Desktop Extension (.mcpb)

The easiest way to install this MCP server in Claude Desktop is using the Desktop Extension bundle:

Option 1: From Official Directory (Recommended)

Open Claude Desktop
Go to Settings → Extensions
Click "Browse extensions"
Search for "AMPECO Public API"
Click Install and follow the configuration prompts

Option 2: Manual Installation

Download the latest .mcpb file from the releases page
Open Claude Desktop
Go to Settings → Extensions
Click "Install Extension..."
Select the downloaded .mcpb file
Configure the required settings:
- API Hostname: Your AMPECO API server (e.g., https://api.example.com)
- Bearer Token: Your AMPECO API authentication token

The extension will automatically operate in resource emulation mode for Claude Desktop compatibility.

Manual Configuration (Advanced)

If you prefer manual configuration or want to customize the setup:

Claude Desktop Configuration

Claude Desktop uses a configuration file called claude_desktop_config.json located at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

You can also access this file through Claude Desktop: Settings → Developer → Edit Config

Configuration Example

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "ampeco-api": {
      "command": "npx",
      "args": [
        "-y",
        "@ampeco/public-api-mcp",
        "--stdio",
        "--hostname",
        "https://api.example.com",
        "--emulate-resources-via-tools"
      ],
      "env": {
        "AMPECO_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

Replace:

https://api.example.com with your actual API hostname
your-token-here with your bearer token

After editing the file, restart Claude Desktop for changes to take effect

What is Tool Emulation Mode?

When --emulate-resources-via-tools is enabled, the server provides two additional tools:

list_resources: Discover available API tags (e.g., Users, ChargingSessions)
- No parameters required
- Returns list of tags that group related endpoints
read_resource: Read endpoint definitions by URI
- Parameter: uri (e.g., tag://Users or api://GET/users/{id})
- Returns full endpoint specification

These tools provide identical functionality to native MCP resources but work through the tools interface that Claude Desktop supports.

Tool Schemas (Emulation Mode)

When --emulate-resources-via-tools is enabled, the following tools are available:

`list_resources` Tool

Description: List all available API tags. This emulates the native MCP resources/list functionality. Returns a list of tags that group related endpoints together (e.g., Users, ChargingSessions, Connectors). Each tag can then be read using the read_resource tool with tag:// URIs.

Parameters: None

Returns: JSON object with resources array containing:

{
  "resources": [
    {
      "uri": "tag://Users",
      "name": "Users",
      "description": "15 endpoints tagged with 'Users'",
      "mimeType": "application/json"
    },
    {
      "uri": "tag://ChargingSessions",
      "name": "ChargingSessions",
      "description": "8 endpoints tagged with 'ChargingSessions'",
      "mimeType": "application/json"
    }
  ]
}

Example Usage:

Call list_resources tool → Get list of all API tags

`read_resource` Tool

Description: Read a specific resource by URI. This emulates the native MCP resources/read functionality. Supports two URI formats: tag://{TagName} to read all endpoints within a tag, and api://{METHOD}{path} to read detailed endpoint specifications. You MUST use this tool to read endpoint definitions before calling api_request.

Parameters:

uri (string, required): The resource URI to read
- Format: tag://{TagName} or api://{METHOD}{path}
- Examples: "tag://Users", "api://GET/users/{id}", "api://POST/charging-sessions"

Returns (for tag URIs):

{
  "tag": "Users",
  "count": 15,
  "endpoints": [
    {
      "uri": "api://GET/users/{id}",
      "method": "GET",
      "path": "/users/{id}",
      "summary": "Get user by ID",
      "operationId": "getUser"
    }
  ]
}

Returns (for api URIs):

{
  "path": "/users/{id}",
  "method": "GET",
  "operationId": "getUser",
  "summary": "Get user by ID",
  "description": "Retrieves detailed information about a specific user",
  "parameters": [...],
  "requestBody": {...},
  "responses": {...},
  "security": "Include token in Authorization header as: Authorization: Bearer <token>"
}

Example Usage:

1. Call read_resource with uri="tag://Users" → Get all endpoints in Users tag
2. Call read_resource with uri="api://GET/users/{id}" → Get full endpoint specification
3. Call api_request with correct parameters → Make the actual API call

When to Use Each Mode

Mode	Use For	Clients
Native Resources (default)	MCP clients that fully support resources	Claude Code, MCP Inspector
Tool Emulation (`--emulate-resources-via-tools`)	Clients without resource support	Claude Desktop

Important Distinction:

Claude Code (the CLI tool): Supports native MCP resources - use default mode
Claude Desktop (the desktop app): Does NOT support resources - use --emulate-resources-via-tools

Rule of thumb: If you're using Claude Desktop, always add --emulate-resources-via-tools. If using Claude Code, use default mode.

Setting Up with Claude Code

The MCP server supports two transport modes:

Stdio Mode (Recommended): Direct process communication for local development and production
HTTP Mode: Remote server access via HTTP transport

Stdio Mode (Local Development)

For development with hot reloading and build integration:

Option 1: One-Liner (Recommended)

# Add dev server with a single command
claude mcp add --transport stdio ampeco-api-dev \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- bash -c "cd /absolute/path/to/public-api-mcp && npm run dev:stdio"

Replace:

/absolute/path/to/public-api-mcp with your actual project path
your-token-here with your API token

Features:

Automatically creates .mcp.json configuration
Rebuilds on each start for hot reloading
All build output redirected to stderr (clean protocol)

Option 2: Manual Configuration

If you prefer to manually edit configuration files:

Set environment variable (optional, for substitution):

export AMPECO_BEARER_TOKEN="your-token-here"
source ~/.bashrc  # or ~/.zshrc

Create .mcp.json in project root:

{
  "mcpServers": {
    "ampeco-api-dev": {
      "type": "stdio",
      "command": "bash",
      "args": ["-c", "cd /absolute/path/to/public-api-mcp && npm run dev:stdio"],
      "env": {"AMPECO_BEARER_TOKEN": "${AMPECO_BEARER_TOKEN}"}
    }
  }
}

Reload: Claude Code will auto-detect the configuration

Stdio Mode (Production via NPX)

For production use without needing the source code:

Option 1: One-Liner (Recommended)

# Add production server with a single command (native resources)
claude mcp add --transport stdio ampeco-api \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- npx -y @ampeco/public-api-mcp --stdio --hostname https://api.example.com

# With tool emulation mode (if client doesn't support resources)
claude mcp add --transport stdio ampeco-api \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- npx -y @ampeco/public-api-mcp --stdio --hostname https://api.example.com --emulate-resources-via-tools

Replace:

your-token-here with your API token
https://api.example.com with your target API hostname

Features:

NPX downloads and caches the package automatically
No source code or build required
Works from any directory
Add --emulate-resources-via-tools for Claude Desktop compatibility

Option 2: Manual Configuration

Create .mcp.json in your project or home directory:

Native Resources Mode:

{
  "mcpServers": {
    "ampeco-api": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ampeco/public-api-mcp",
        "--stdio",
        "--hostname",
        "https://api.example.com"
      ],
      "env": {
        "AMPECO_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

Tool Emulation Mode (for Claude Desktop):

{
  "mcpServers": {
    "ampeco-api": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ampeco/public-api-mcp",
        "--stdio",
        "--hostname",
        "https://api.example.com",
        "--emulate-resources-via-tools"
      ],
      "env": {
        "AMPECO_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

Using environment variables (more secure):

export AMPECO_BEARER_TOKEN="your-token-here"

Then use "${AMPECO_BEARER_TOKEN}" in the JSON config.

Stdio Mode (Production via Global Install)

For faster startup without NPX overhead:

1. Install Globally

npm install -g @ampeco/public-api-mcp

2. Add to Claude Code (One-Liner)

# Add globally installed server (native resources)
claude mcp add --transport stdio ampeco-api \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- ampeco-api-mcp --stdio --hostname https://api.example.com

# With tool emulation mode (for Claude Desktop)
claude mcp add --transport stdio ampeco-api \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- ampeco-api-mcp --stdio --hostname https://api.example.com --emulate-resources-via-tools

Or manual configuration in .mcp.json:

Native Resources Mode:

{
  "mcpServers": {
    "ampeco-api": {
      "type": "stdio",
      "command": "ampeco-api-mcp",
      "args": ["--stdio", "--hostname", "https://api.example.com"],
      "env": {"AMPECO_BEARER_TOKEN": "your-token-here"}
    }
  }
}

Tool Emulation Mode (for Claude Desktop):

{
  "mcpServers": {
    "ampeco-api": {
      "type": "stdio",
      "command": "ampeco-api-mcp",
      "args": [
        "--stdio",
        "--hostname",
        "https://api.example.com",
        "--emulate-resources-via-tools"
      ],
      "env": {"AMPECO_BEARER_TOKEN": "your-token-here"}
    }
  }
}

HTTP Mode (Remote Server)

For shared server access or when multiple clients need to connect:

1. Start the Server

# Development mode (native resources)
PORT=3001 npm run dev:http

# Development mode (tool emulation)
PORT=3001 npm start -- --http --port 3001 --emulate-resources-via-tools

# Production mode (native resources)
npm run build  # First time only
PORT=3001 npm start -- --http --port 3001

# Production mode (tool emulation)
npm run build  # First time only
PORT=3001 npm start -- --http --port 3001 --emulate-resources-via-tools

2. Add to Claude Code (One-Liner)

# Add HTTP server with a single command
claude mcp add --transport http ampeco-api \
  http://localhost:3001/api.example.com \
  --header "Authorization: Bearer your-token-here"

With protocol override (use HTTP for target API instead of HTTPS):

claude mcp add --transport http ampeco-api \
  http://localhost:3001/api.example.com/http \
  --header "Authorization: Bearer your-token-here"

Or manual configuration in .mcp.json:

{
  "mcpServers": {
    "ampeco-api-http": {
      "type": "http",
      "url": "http://localhost:3001/api.example.com",
      "headers": {"Authorization": "Bearer your-token-here"}
    }
  }
}

Notes:

Server must be running before connecting
Target API hostname is in the URL path
Optional /http or /https suffix controls target API protocol
Defaults to HTTPS if not specified

Comparison: Stdio vs HTTP Mode

Feature	Stdio Mode	HTTP Mode
Use Case	Local development, single user	Remote access, multiple clients
Setup Complexity	Simple (just config file)	Requires running server
Performance	Faster (no HTTP overhead)	Slightly slower (HTTP latency)
Security	More secure (local only)	Network exposure (use HTTPS in prod)
Hot Reload	Yes (dev mode)	Requires server restart
Multi-Client	No (one client at a time)	Yes (concurrent clients)
Memory Usage	Lower (~30MB per instance)	Higher (~50MB + per-request)

Recommendation: Use stdio mode for development and single-user production. Use HTTP mode for shared servers or when multiple clients need concurrent access.

Troubleshooting

Stdio Mode Issues

Problem: Server not starting or connection fails

# List configured MCP servers
claude mcp list

# Check status
claude mcp status ampeco-api-dev

# Remove and re-add the server
claude mcp remove ampeco-api-dev
claude mcp add --transport stdio ampeco-api-dev \
  --env AMPECO_BEARER_TOKEN=your-token \
  -- bash -c "cd /path/to/public-api-mcp && npm run dev:stdio"

# Verify the command works standalone
cd /path/to/public-api-mcp
AMPECO_BEARER_TOKEN=your-token npm run dev:stdio

Problem: Build output interfering with protocol

This is fixed in dev:stdio script which redirects build output to stderr
For production, run npm run build first, then use the compiled CLI

Problem: Environment variables not loading

# Verify environment variable is set
echo $AMPECO_BEARER_TOKEN

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc

HTTP Mode Issues

Problem: Server not accessible

# Test server health
curl http://localhost:3001/health

# Check if port is in use
lsof -i :3001

# Try a different port
PORT=3002 npm run dev:http

Problem: CORS errors

The server has CORS enabled for all origins
Check browser console for specific error messages

General Issues

Problem: Endpoints not loading

# Verify build artifacts exist
ls -la src/generated/

# Rebuild if needed
npm run build

Problem: Authentication errors

Verify your AMPECO_BEARER_TOKEN is correct
Check the token has proper permissions for the API

Test the token directly with the API:

curl -H "Authorization: Bearer your-token" \
  https://api.example.com/health

Building Desktop Extension (.mcpb)

To package this MCP server as a Desktop Extension for distribution:

# Build and package as .mcpb
npm run package:mcpb

This creates a .mcpb file (e.g., ampeco-api-mcp-0.3.0.mcpb) that can be:

Distributed to users for manual installation
Submitted to the official Claude Desktop extensions directory
Shared within your organization

The .mcpb file is a self-contained bundle including:

Compiled server code (dist/)
All dependencies (via package.json)
Extension metadata (manifest.json)
Documentation (README.md)

What's Included in the Bundle

The Desktop Extension bundle operates in resource emulation mode by default, which means:

Full compatibility with Claude Desktop (no native resource support needed)
list_resources and read_resource tools for endpoint discovery
api_request tool for making authenticated API calls
Automatic token management via environment variables

Users only need to provide two configuration values during installation:

API Hostname: The AMPECO API server URL
Bearer Token: Their authentication token

Technology Stack

Runtime

Language: TypeScript / Node.js (ES2022 modules)
Server: Express
MCP SDK: @modelcontextprotocol/sdk
HTTP Client: node-fetch
Validation: zod

Build-Time

OpenAPI Parser: @readme/openapi-parser
Build Tools: tsx, TypeScript compiler

Development

Type Checking: TypeScript (strict mode)
Testing: Vitest (planned)

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
.claude		.claude
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src		src
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CLI_TESTING_README.md		CLI_TESTING_README.md
CLI_TEST_EXAMPLES.md		CLI_TEST_EXAMPLES.md
LICENSE		LICENSE
PLAN.md		PLAN.md
README.md		README.md
manifest.json		manifest.json
package-lock.json		package-lock.json
package.json		package.json
test-inspector-cli.sh		test-inspector-cli.sh
tsconfig.json		tsconfig.json

License

ampeco/public-api-mcp

Folders and files

Latest commit

History

Repository files navigation

Public API MCP Server

Quick Start

Development (Stdio Mode)

Production (via NPX)

HTTP Mode (Remote Server)

Overview

Usage

Running the Build Pipeline

Development

Architecture

Build-Time Pipeline

MCP Server

Resource Modes

Running the Server

Server Endpoints

Setting Up with Claude Desktop

Installation via Desktop Extension (.mcpb)

Option 1: From Official Directory (Recommended)

Option 2: Manual Installation

Manual Configuration (Advanced)

Claude Desktop Configuration

Configuration Example

What is Tool Emulation Mode?

Tool Schemas (Emulation Mode)

list_resources Tool

read_resource Tool

When to Use Each Mode

Setting Up with Claude Code

Stdio Mode (Local Development)

Option 1: One-Liner (Recommended)

Option 2: Manual Configuration

Stdio Mode (Production via NPX)

Option 1: One-Liner (Recommended)

Option 2: Manual Configuration

Stdio Mode (Production via Global Install)

1. Install Globally

2. Add to Claude Code (One-Liner)

HTTP Mode (Remote Server)

1. Start the Server

2. Add to Claude Code (One-Liner)

Comparison: Stdio vs HTTP Mode

Troubleshooting

Stdio Mode Issues

HTTP Mode Issues

General Issues

Building Desktop Extension (.mcpb)

What's Included in the Bundle

Technology Stack

Runtime

Build-Time

Development

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`list_resources` Tool

`read_resource` Tool

Packages