MCP HTTP Bridge

A generic stdio MCP (Model Context Protocol) to HTTP API bridge that exposes OpenAPI endpoints as MCP tools for use with Claude and other AI assistants.

🚀 Features

- OpenAPI/Swagger Support: Automatically generate MCP tools from OpenAPI 3.0 specifications
- Multiple Spec Sources: Load from local files, remote URLs, or inline content
- Flexible Authentication: Bearer tokens, Basic auth, API keys, custom headers, or token files
- Fast & Lightweight: Optimized for quick responses with configurable timeouts and retries
- CLI Integration: Easy command-line interface with comprehensive options
- Standalone Executable: Self-contained 628K executable with zero dependencies - perfect for Electron apps and containers
- MCP Config Generation: Generate ready-to-use MCP server configurations (uses npx by default)
- Filtering & Validation: Filter tools by tags or operation IDs, validate API responses
- Real-time Testing: Built-in integration tests with fast execution
- Secure Token Management: Load sensitive tokens from files instead of command line
- Dynamic Token Reading: Auth files are read fresh on each API call, enabling token rotation
- Advanced Tool Filtering: Whitelist/blacklist tools with --allowed-tools and --disallowed-tools
- Cascade Parameter System: Set fixed/context parameters that cannot be overridden by agents for enhanced security
- Comprehensive Logging: Enhanced debugging with --log to capture invocation parameters and file contents
- Tool Discovery: Built-in discovery mode to explore available tools before deployment
- Command-line Tool Invocation: Test individual API endpoints directly from the command line
- Custom Mappings: Configure tool behavior with mappings files for parameter transformation and response formatting
- Custom Tool Mappings: Create semantic, workflow-oriented tool names with fixed parameters - multiple tools per endpoint supported

📦 Installation

$3

``bash
npm install -g @majkapp/mcp-http-bridge
`

$3

`bash
npm install @majkapp/mcp-http-bridge
`

$3

For environments where you need a self-contained executable without Node.js dependencies (perfect for Electron apps and containerized deployments):

`bash


Install the package first

npm install -g @majkapp/mcp-http-bridge

Use the standalone executable

mcp-http-bridge-standalone --spec ./api.yaml --auth-bearer "token"
`

Key Benefits:
- 🎯 Zero Dependencies: Single 628K file with all dependencies bundled
- ⚡ Direct Execution: No node_modules/ required
- 📦 Electron-Friendly: Perfect for Electron app packaging
- 🚀 Container-Ready: Ideal for Docker images and serverless deployments
- 🔒 Same Functionality: All CLI options and features preserved

File Location:
`bash


After npm install, the standalone executable is available at:

node_modules/@majkapp/mcp-http-bridge/dist/mcp-http-bridge-standalone.cjs

Or use directly via npx:

npx @majkapp/mcp-http-bridge-standalone --spec ./api.yaml
`

🎯 Quick Start

$3

`bash

Using an OpenAPI spec file

mcp-http-bridge --spec ./api.yaml

Fetch OpenAPI spec from URL

mcp-http-bridge --spec-url https://api.example.com/openapi.json

Using inline spec content

mcp-http-bridge --spec-content '{"openapi":"3.0.0",...}'
`

$3

`bash

Bearer token from command line

mcp-http-bridge --spec ./api.yaml --auth-bearer "your-token-here"

Bearer token from file (secure approach - read dynamically on each request)

mcp-http-bridge --spec ./api.yaml --auth-file ./token.txt

API key in header

mcp-http-bridge --spec ./api.yaml --auth-api-key "X-API-Key:your-key"

Basic authentication

mcp-http-bridge --spec ./api.yaml --auth-basic "username:password"

Custom headers

mcp-http-bridge --spec ./api.yaml --auth-custom-headers '{"Authorization":"Bearer token"}'
`

$3

`bash

Set fixed parameters that agents cannot override

mcp-http-bridge --spec ./api.yaml --cascade 'user_id=12345!' --cascade 'tenant=acme-corp!'

Route-specific restrictions

mcp-http-bridge --spec ./api.yaml --cascade '@createUser:read_only=true!' --cascade '@deleteUser:require_approval=true!'

Load configuration from file with environment variables

mcp-http-bridge --spec ./api.yaml --cascade-file ./cascade-config.yaml --cascade 'session_id=${ENV.SESSION_ID}!'
`

Auth File Format Examples:
`bash


token.txt can contain any of these formats:

echo "Bearer sk-your-token-123" > token.txt # Bearer token
echo "Basic dXNlcjpwYXNzd29yZA==" > token.txt # Basic auth
echo "sk-your-token-123" > token.txt # Raw token (auto-prefixed with Bearer)

Tilde paths are supported (expanded to home directory):

echo "Bearer sk-token" > ~/.majk/.majk.token # ~/path/to/file
echo "Bearer sk-token" > ~/.config/mcp/token.txt # Nested directories
`

$3

`bash

Generate MCP server config (uses npx by default)

mcp-http-bridge --spec ./api.yaml --mcp-config my-api-server

Generate config with URL and auth file

mcp-http-bridge --spec-url https://api.example.com/openapi.json --auth-file ./token.txt --mcp-config my-api

Generate config with custom command path

mcp-http-bridge --spec ./api.yaml --command-path /usr/local/bin/mcp-http-bridge --mcp-config my-api
`

🔧 CLI Options

| Option | Description | Example |
|--------|-------------|---------|
| --spec | Path to OpenAPI specification file | --spec ./api.yaml |
| --spec-url | URL to OpenAPI specification | --spec-url https://api.example.com/openapi.json |
| --spec-content | OpenAPI spec as string | --spec-content '{...}' |
| --auth-file | Path to file containing auth token (supports ~) | --auth-file ~/.majk/.majk.token |
| --base-url | Override base URL | --base-url https://api.example.com |
| --auth-bearer | Bearer token auth | --auth-bearer "jwt-token" |
| --auth-basic | Basic authentication | --auth-basic "user:pass" |
| --auth-api-key | API key in header | --auth-api-key "X-API-Key:key" |
| --auth-api-key-query | API key in query | --auth-api-key-query "apikey:key" |
| --auth-custom-headers | Custom headers | --auth-custom-headers '{"X-Custom":"value"}' |
| --timeout | Request timeout | --timeout 5000 |
| --retries | Number of retries | --retries 3 |
| --rate-limit | Max requests per second | --rate-limit 10 |
| --tag-filter | Filter by tags | --tag-filter "users,posts" |
| --operation-filter | Filter by operation IDs | --operation-filter "getUser,createPost" |
| --allowed-tools | Whitelist specific tools | --allowed-tools "getUser,createPost" |
| --disallowed-tools | Blacklist specific tools | --disallowed-tools "deleteUser,deletePost" |
| --mappings-file | Use custom tool mappings | --mappings-file ./mappings.json |
| --generate-mappings | Generate initial mappings file | --generate-mappings ./mappings.json |
| --discover | Discover available tools and exit | --discover |
| --discover-format | Discovery output format | --discover-format json |
| --invoke | Invoke a specific tool | --invoke getUser |
| --invoke-params | JSON parameters for invocation | --invoke-params '{"id":123}' |
| --param | Key-value parameters (multiple) | --param id=123 --param name=John |
| --validate-responses | Validate API responses | --validate-responses |
| --include-deprecated | Include deprecated operations | --include-deprecated |
| --mcp-config [name] | Generate MCP config | --mcp-config my-server |
| --cascade | Set fixed/context parameters (multiple) | --cascade 'user_id=123!' |
| --cascade-file | Load cascade configuration file | --cascade-file ./cascade.yaml |
| --command-path | Command for MCP config | --command-path mcp-http-bridge |
| --verbose | Enable verbose logging | --verbose |
| --debug | Enable debug logging | --debug |
| --log | Log detailed debug information | --log debug.log |

🔗 Cascade Parameter System

The cascade parameter system enables you to set fixed parameters that cannot be overridden by MCP agents, providing enhanced security, consistency, and control over API interactions.

$3

- Security: Fix critical parameters like user IDs, tenant IDs, and permissions
- Consistency: Ensure certain values remain constant across all operations
- Multi-tenancy: Enforce tenant isolation automatically
- Compliance: Meet audit requirements with immutable parameters
- Flexibility: Apply parameters globally or to specific operations

$3

`bash


Fix user identity across all operations

mcp-http-bridge --spec ./api.yaml --cascade 'user_id=12345!' --cascade 'tenant=acme-corp!'

Apply different restrictions to specific operations

mcp-http-bridge --spec ./api.yaml --cascade '@createUser:permissions=read!' --cascade '@deleteUser:require_approval=true!'

Load configuration from file

mcp-http-bridge --spec ./api.yaml --cascade-file ./cascade-config.yaml

Use environment variables for sensitive values

mcp-http-bridge --spec ./api.yaml --cascade 'api_key=${ENV.API_SECRET}!' --cascade 'user_id=${ENV.USER_ID}!'
`

$3

| Format | Description | Example | Effect |
|--------|-------------|---------|--------|
| param=value | Context parameter | --cascade 'debug=true' | Agent can override |
| param=value! | Fixed parameter | --cascade 'user_id=123!' | Agent CANNOT override |
| @route:param=value | Route-specific context | --cascade '@getUser:include_profile=true' | Applied only to getUser operations |
| @route:param=value! | Route-specific fixed | --cascade '@delete*:read_only=true!' | Fixed for matching routes |
| %PROFILE:name | Load profile | --cascade '%PROFILE:production' | Activate named profile from config |
| ${ENV.VAR} | Environment variable | --cascade 'token=${ENV.API_TOKEN}!' | Substitute from environment |

$3

#### YAML Format (Recommended)
`yaml


Global parameters applied to all routes

global:
user_id:
value: "${USER_ID}" # Environment variable substitution
fixed: true # Cannot be overridden
tenant_id:
value: "acme-corp"
fixed: true
api_version:
value: "v2"
fixed: false # Agent can override

Route-specific parameters

routes:
createUser:
permissions:
value: "read"
fixed: true # Force read-only for user creation
notify_admin:
value: true
fixed: true

deleteUser:
require_approval:
value: true
fixed: true # Always require approval for deletion
audit_level:
value: "HIGH"
fixed: true

Named profiles for different environments

profiles:
production:
environment: "prod"
rate_limit: 100
debug: false
strict_validation: true

development:
environment: "dev"
rate_limit: 1000
debug: true
strict_validation: false
`

#### JSON Format
`json
{
"global": {
"user_id": { "value": "12345", "fixed": true },
"tenant_id": { "value": "acme-corp", "fixed": true }
},
"routes": {
"createUser": {
"permissions": { "value": "read", "fixed": true }
}
},
"profiles": {
"production": {
"environment": "prod",
"debug": false
}
}
}
`

$3

Parameters are applied in this priority order (highest first):

1. Agent-provided parameters (for non-fixed params only)
2. Route-specific cascade from command line (--cascade '@route:param=value')
3. Route-specific cascade from config file (routes.routeName.param)
4. Global cascade from command line (--cascade 'param=value')
5. Global cascade from config file (global.param)
6. Profile parameters (if profile is active)

Important: Fixed parameters (marked with ! or fixed: true) cannot be overridden regardless of priority.

$3

#### Multi-Tenant SaaS Protection
`bash


Ensure tenant isolation - agent cannot access other tenants


mcp-http-bridge --spec ./api.yaml \
--cascade 'tenant_id=tenant-123!' \
--cascade 'user_id=user-456!' \
--cascade 'subscription_tier=premium!'
`

#### Read-Only Mode Enforcement
`bash


Force all write operations to read-only mode


mcp-http-bridge --spec ./api.yaml \
--cascade '@create*:read_only=true!' \
--cascade '@update*:read_only=true!' \
--cascade '@delete*:read_only=true!'
`

#### Audit Trail Requirements
`bash


Ensure audit compliance for sensitive operations


mcp-http-bridge --spec ./api.yaml \
--cascade 'audit_user=${ENV.AUDIT_USER}!' \
--cascade 'compliance_mode=strict!' \
--cascade '@deleteUser:require_mfa=true!' \
--cascade '@updatePermissions:log_level=HIGH!'
`

$3

`bash


Set environment variables

export API_USER_ID=12345
export API_TENANT=acme
export API_SECRET=sk-secret-key

Use in cascade parameters

mcp-http-bridge --spec ./api.yaml \
--cascade 'user_id=${ENV.API_USER_ID}!' \
--cascade 'tenant=${ENV.API_TENANT}!' \
--cascade 'api_key=${ENV.API_SECRET}!'
`

$3

Use profiles to manage environment-specific settings:

`bash


Production deployment

mcp-http-bridge --spec ./api.yaml \
--cascade-file ./cascade.yaml \
--cascade '%PROFILE:production'

Development with additional debugging

mcp-http-bridge --spec ./api.yaml \
--cascade-file ./cascade.yaml \
--cascade '%PROFILE:development' \
--cascade 'debug_level=verbose'
`

$3

Test cascade parameters before deployment:

`bash


Test with invoke command to see parameter behavior

mcp-http-bridge --spec ./api.yaml \
--cascade 'user_id=123!' \
--cascade '@createUser:permissions=read!' \
--invoke createUser \
--param name=John \
--param email=john@example.com

The cascade parameters will be automatically applied and protected

`

$3

1. Always fix security-critical parameters: User IDs, tenant IDs, permissions
2. Use environment variables for sensitive values - never hardcode secrets
3. Apply route-specific restrictions for dangerous operations
4. Use profiles to manage different environments (prod/staging/dev)
5. Test thoroughly with --invoke before deploying
6. Document your cascade configuration for your team
7. Use wildcard patterns (@delete, @admin) for operation groups

$3

#### Complete Multi-Environment Setup
`bash


Create environment-specific cascade files

echo 'global:
user_id: { value: "${USER_ID}", fixed: true }
tenant_id: { value: "${TENANT_ID}", fixed: true }
profiles:
production:
rate_limit: 100
timeout: 30000
development:
rate_limit: 1000
timeout: 60000' > cascade.yaml

Production deployment

USER_ID=prod-123 TENANT_ID=tenant-prod mcp-http-bridge \
--spec ./api.yaml \
--cascade-file ./cascade.yaml \
--cascade '%PROFILE:production' \
--mcp-config prod-api

Development deployment

USER_ID=dev-456 TENANT_ID=tenant-dev mcp-http-bridge \
--spec ./api.yaml \
--cascade-file ./cascade.yaml \
--cascade '%PROFILE:development' \
--mcp-config dev-api
`

🔐 Auth File Behavior

The --auth-file option provides secure, dynamic authentication:

$3

- Auth files are read fresh on every API call, not cached at startup
- Enables token rotation without restarting the MCP server
- Missing or unreadable files are handled gracefully (logged but don't crash)

$3

`bash

Any of these formats work in your auth file:

Bearer your-jwt-token-here # Bearer token (preferred)
Basic dXNlcjpwYXNzd29yZA== # Basic authentication
your-raw-token-here # Raw token (auto-prefixed with "Bearer ")
`

$3

- Tokens never appear in command line arguments (hidden from ps output)
- Supports external token management systems
- Enables automatic token refresh workflows
- File permissions can restrict access (e.g., chmod 600 token.txt)

$3

`bash

Create secure token file in home directory

mkdir -p ~/.majk
echo "Bearer sk-your-secret-token" > ~/.majk/.majk.token
chmod 600 ~/.majk/.majk.token

Generate MCP config with tilde path (expands to full path)

mcp-http-bridge --spec ./api.yaml --auth-file ~/.majk/.majk.token --mcp-config my-api

Or use relative paths

echo "Bearer sk-token" > ./token.txt
chmod 600 ./token.txt
mcp-http-bridge --spec ./api.yaml --auth-file ./token.txt --mcp-config my-api
`

🔍 Tool Discovery & Testing

$3

Before deploying your MCP server, you can explore all available tools generated from your OpenAPI spec:

`bash


Human-readable discovery output

mcp-http-bridge --spec ./api.yaml --discover

JSON output for programmatic use

mcp-http-bridge --spec ./api.yaml --discover --discover-format json

MCP format output

mcp-http-bridge --spec ./api.yaml --discover --discover-format mcp
`

Example output (human format):
`
📋 Discovered 6 tools from OpenAPI specification

🔧 getPosts
Description: Get all posts
Parameters: _limit (integer, optional) - Limit the number of results

🔧 createPost
Description: Create a new post
Parameters: title (string, required), body (string, required), userId (integer, required)

🔧 getPost
Description: Get a post by ID
Parameters: id (integer, required) - Post ID

... (additional tools)
`

$3

Test individual API endpoints directly from the command line:

`bash


Invoke with key-value parameters

mcp-http-bridge --spec ./api.yaml --invoke getUser --param id=1

Invoke with JSON parameters

mcp-http-bridge --spec ./api.yaml --invoke createPost --invoke-params '{"title":"Test","body":"Content","userId":1}'

Mix both parameter styles

mcp-http-bridge --spec ./api.yaml --invoke updatePost --param id=1 --invoke-params '{"title":"Updated Title"}'

With authentication

mcp-http-bridge --spec ./api.yaml --auth-file ./token.txt --invoke getUser --param id=1
`

This is perfect for:
- Testing API endpoints before deploying the MCP server
- Debugging authentication and parameter issues
- Validating OpenAPI spec compatibility
- Quick API exploration and development

🎯 Tool Filtering

Control which tools are available to prevent unwanted API access:

$3

Only allow specific tools to be available:

`bash


Allow only safe read operations

mcp-http-bridge --spec ./api.yaml --allowed-tools "getUser,getPost,getPosts"

Allow user management operations

mcp-http-bridge --spec ./api.yaml --allowed-tools "getUser,createUser,updateUser"
`

$3

Block specific dangerous operations:

`bash


Block all delete operations

mcp-http-bridge --spec ./api.yaml --disallowed-tools "deleteUser,deletePost,deleteComment"

Block admin operations

mcp-http-bridge --spec ./api.yaml --disallowed-tools "deleteUser,updateUserRole,systemReset"
`

$3

Use discovery to identify tool names, then filter appropriately:

`bash


1. Discover all available tools

mcp-http-bridge --spec ./api.yaml --discover --discover-format json > tools.json

2. Review the tools and identify safe ones

cat tools.json | jq '.tools[].name'

3. Create a filtered MCP config with only safe tools

mcp-http-bridge --spec ./api.yaml --allowed-tools "getUser,getPost" --mcp-config safe-api
`

Security Note: Tool filtering happens at both discovery time and runtime, preventing unauthorized tool access even if the tool names are known.

📁 Custom Tool Mappings

Customize tool behavior with mappings files to transform parameters, modify responses, or rename tools:

$3

`bash

Generate a starter mappings file based on your OpenAPI spec

mcp-http-bridge --spec ./api.yaml --generate-mappings ./mappings.json
`

This creates a mappings file with all discovered tools that you can customize.

$3

`json
{
"mappings": {
"getUserById": {
"name": "getUser",
"description": "Retrieve user information by ID",
"parameters": {
"id": {
"target": "path",
"required": true
},
"include_profile": {
"target": "query",
"name": "include",
"default": "profile"
}
},
"headers": {
"X-Client": "MCP-Bridge"
},
"responseTransform": "{{data.name}} ({{data.email}})"
}
},
"globalDefaults": {
"headers": {
"User-Agent": "MCP-HTTP-Bridge/1.2.0"
}
}
}
`

$3

`bash

Apply your custom mappings

mcp-http-bridge --spec ./api.yaml --mappings-file ./mappings.json

Generate MCP config with custom mappings

mcp-http-bridge --spec ./api.yaml --mappings-file ./mappings.json --mcp-config custom-api
`

$3

- Rename tools: Change tool names for better clarity
- Transform parameters: Map parameters to different locations (path, query, header, body)
- Set defaults: Provide default values for parameters
- Custom headers: Add tool-specific or global headers
- Response formatting: Transform API responses with Handlebars templates
- Parameter validation: Mark parameters as required/optional

🎯 Workflow-Oriented Tool Mappings (New!)

Create semantic, workflow-oriented tool names with pre-configured parameters using --tool-mappings. This powerful feature allows you to create multiple custom tools that call the same REST endpoint with different fixed parameters.

$3

- Semantic Tool Names: Replace auto-generated names like get__api_projects_abc123 with workflow-oriented names like current_project_read
- Fixed Parameters: Pre-configure tools with specific parameters that are automatically injected
- Multiple Tools Per Endpoint: Create different tools that call the same API endpoint with different configurations
- Mixed Mode: Customize only the endpoints you need while keeping others auto-generated
- Workflow Context: Tools are pre-configured for specific business contexts and use cases

$3

`bash


Create workflow-oriented tools with fixed parameters


mcp-http-bridge --spec ./api.yaml --tool-mappings '{
"current_project_read": {
"operation": "getProjectById",
"fixedParams": "id=current-project&context=active",
"description": "Read the project I am currently working on"
},
"client_project_read": {
"operation": "getProjectById",
"fixedParams": "id=client-project&context=client",
"description": "Read the client project details"
}
}'
`

$3

`typescript
interface ToolMapping {
operation: string; // OpenAPI operation ID to call
fixedParams?: string; // Query params always sent (URL encoded)
description?: string; // Override tool description
parameters?: object; // Override/extend tool parameters schema
}

interface ToolMappingsConfig {
[customToolName: string]: ToolMapping;
}
`

$3

#### Multi-Tenant Application
`bash
mcp-http-bridge --spec ./api.yaml --tool-mappings '{
"tenant_alpha_users": {
"operation": "listUsers",
"fixedParams": "tenantId=alpha",
"description": "List users for tenant Alpha"
},
"tenant_beta_users": {
"operation": "listUsers",
"fixedParams": "tenantId=beta",
"description": "List users for tenant Beta"
},
"admin_users_list": {
"operation": "listUsers",
"fixedParams": "role=admin",
"description": "List admin users across all tenants"
}
}'
`

#### Development Workflow
`bash
mcp-http-bridge --spec ./api.yaml --tool-mappings '{
"my_active_projects": {
"operation": "listProjects",
"fixedParams": "filter=active&assignee=me&limit=20",
"description": "List my active projects"
},
"production_health_check": {
"operation": "getSystemStatus",
"fixedParams": "environment=production&detailed=true",
"description": "Check production system health"
}
}'
`

#### Multi-Environment Management
`bash
mcp-http-bridge --spec ./api.yaml --tool-mappings '{
"prod_deploy_status": {
"operation": "getDeploymentStatus",
"fixedParams": "environment=production&includeMetrics=true",
"description": "Production deployment status with metrics"
},
"staging_deploy_status": {
"operation": "getDeploymentStatus",
"fixedParams": "environment=staging&includeMetrics=false",
"description": "Staging deployment status overview"
}
}'
`

$3

Parameters are applied in this order:
`
Final Request = Base URL + Operation Path + Fixed Params + Cascade Params + User Params
↑ Highest precedence
`

- Fixed Parameters (from fixedParams): Highest precedence, cannot be overridden
- Cascade Parameters (from --cascade): Applied if no fixed parameter conflicts
- User Parameters (from Claude): Applied if no conflicts with fixed or cascade

$3

Tool mappings work in mixed mode - you can customize specific endpoints while keeping others auto-generated:

`bash


This creates:

✅ current_project_read (custom tool with fixed params)

✅ client_project_read (custom tool with fixed params)

✅ createUser (auto-generated tool, unchanged)

✅ updateUser (auto-generated tool, unchanged)

✅ deleteUser (auto-generated tool, unchanged)

✅ ... all other auto-generated tools

mcp-http-bridge --spec ./api.yaml --tool-mappings '{
"current_project_read": {
"operation": "getProjectById",
"fixedParams": "id=current",
"description": "Read current project"
},
"client_project_read": {
"operation": "getProjectById",
"fixedParams": "id=client",
"description": "Read client project"
}
}'
`

$3

Tool mappings work seamlessly with existing filtering options:

`bash


Allow only specific custom and auto-generated tools

mcp-http-bridge --spec ./api.yaml \
--tool-mappings '{"current_project":"getProject","fixedParams":"id=current"}' \
--allowed-tools "current_project,createUser,updateUser"

Block specific custom or auto-generated tools

mcp-http-bridge --spec ./api.yaml \
--tool-mappings '{"admin_tools":"getAdminData","fixedParams":"role=admin"}' \
--disallowed-tools "deleteUser,admin_tools"
`

$3

`bash


Discover your custom workflow tools


mcp-http-bridge --spec ./api.yaml \
--tool-mappings '{"current_project":"getProject","fixedParams":"id=current"}' \
--discover --discover-format human
`

$3

Fixed parameters support URL encoding for special characters:

`bash


URL encode special characters in fixedParams


mcp-http-bridge --spec ./api.yaml --tool-mappings '{
"project_with_spaces": {
"operation": "getProject",
"fixedParams": "id=project%20with%20spaces&context=test%26demo"
}
}'
`

📊 Enhanced Logging & Debugging

Get comprehensive debugging information with the --log option:

`bash


Enable detailed logging to file

mcp-http-bridge --spec ./api.yaml --auth-file ./token.txt --log debug.log

With verbose output

mcp-http-bridge --spec ./api.yaml --verbose --debug --log debug.log
`

$3

The debug log captures everything needed for troubleshooting:

1. Invocation Parameters: Complete command line arguments and environment
2. Spec Content: Full OpenAPI specification content (from file, URL, or inline)
3. Auth File Operations: When auth files are read, including content and errors
4. HTTP Requests: Complete request details including headers, body, and URL
5. HTTP Responses: Full response data, headers, and status codes
6. MCP Messages: All MCP protocol messages sent and received
7. Errors: Detailed error information with stack traces

$3

`
========================================
MCP HTTP Bridge Debug Log
Started: 2024-01-15T10:30:00.000Z
========================================

[2024-01-15T10:30:00.123Z] Invocation Parameters
----------------------------------------
Command: node /path/to/index.js
Arguments: --spec ./api.yaml --auth-file ./token.txt --log debug.log
Full argv: ["node", "/path/to/index.js", "--spec", "./api.yaml", ...]
----------------------------------------

[2024-01-15T10:30:00.456Z] Spec File Content
----------------------------------------
Source: /full/path/to/api.yaml
Content Length: 2847 characters

Content:
openapi: 3.0.0
info:
title: My API
...
----------------------------------------

[2024-01-15T10:30:05.789Z] HTTP Request
----------------------------------------
POST https://api.example.com/users HTTP/1.1

Headers:
Authorization: Bearer sk-xxx...
Content-Type: application/json
User-Agent: MCP-HTTP-Bridge/1.2.0

Body:
{
"name": "John Doe",
"email": "john@example.com"
}
----------------------------------------
`

This logging is invaluable for:
- Debugging authentication issues: See exactly what tokens are being sent
- Troubleshooting API calls: View complete request/response cycles
- Understanding tool behavior: Track how MCP messages are processed
- Performance analysis: Monitor request timing and patterns
- Security auditing: Review all API interactions and parameters

📋 Ready-to-Use Examples

$3

The easiest way to get started is by generating MCP configurations directly from your OpenAPI specs:

#### From a local file
`bash
mcp-http-bridge --spec ./api.yaml --mcp-config my-api
`

Output:
`json
{
"mcpServers": {
"my-api": {
"command": "npx",
"args": [
"@majkapp/mcp-http-bridge",
"--spec",
"/full/path/to/api.yaml"
]
}
}
}
`

#### From a URL with authentication
`bash
mcp-http-bridge --spec-url https://api.github.com/openapi.json --auth-file ./github-token.txt --mcp-config github-api
`

Output:
`json
{
"mcpServers": {
"github-api": {
"command": "npx",
"args": [
"@majkapp/mcp-http-bridge",
"--spec-url",
"https://api.github.com/openapi.json",
"--auth-file",
"/full/path/to/github-token.txt"
]
}
}
}
`

$3

#### JSONPlaceholder API (Testing)
`json
{
"mcpServers": {
"jsonplaceholder": {
"command": "npx",
"args": [
"@majkapp/mcp-http-bridge",
"--spec-url",
"https://jsonplaceholder.typicode.com/openapi.json"
]
}
}
}
`

#### OpenAI API (with auth file)
Create a secure token file:
`bash


Create the token file with proper format

echo "Bearer sk-your-openai-api-key-here" > openai-token.txt
chmod 600 openai-token.txt # Secure file permissions

Generate MCP config

mcp-http-bridge --spec-url https://api.openai.com/v1/openapi.json --auth-file ./openai-token.txt --mcp-config openai
`

Note: The token will be read fresh from openai-token.txt on every API call, so you can update it anytime without restarting the MCP server.

#### Stripe API (with API key in header)
`json
{
"mcpServers": {
"stripe": {
"command": "npx",
"args": [
"@majkapp/mcp-http-bridge",
"--spec-url",
"https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json",
"--auth-api-key",
"Authorization:Bearer sk_test_your_stripe_key"
]
}
}
}
`

#### Local API Development
For APIs in development with custom authentication:
`json
{
"mcpServers": {
"my-local-api": {
"command": "npx",
"args": [
"@majkapp/mcp-http-bridge",
"--spec",
"/path/to/local/api.yaml",
"--base-url",
"http://localhost:3000",
"--auth-custom-headers",
"{\"X-API-Key\":\"dev-key-123\",\"X-Tenant\":\"development\"}"
]
}
}
}
`

$3

#### With tool filtering, validation, and cascade parameters
`bash


Only include user and post related operations with fixed tenant isolation

mcp-http-bridge --spec ./api.yaml --tag-filter "users,posts" --validate-responses \
--cascade 'tenant_id=secure-tenant!' --cascade 'user_id=${ENV.API_USER_ID}!' \
--mcp-config filtered-api

Include only specific operations with read-only enforcement

mcp-http-bridge --spec ./api.yaml --operation-filter "getUser,createUser,updateUser" \
--cascade '@createUser:read_only=true!' --cascade '@updateUser:require_approval=true!' \
--mcp-config user-api

Whitelist only safe operations with audit trail

mcp-http-bridge --spec ./api.yaml --allowed-tools "getUser,getPost,getPosts" \
--cascade 'audit_mode=enabled!' --cascade 'session_id=${ENV.SESSION_ID}!' \
--mcp-config safe-api

Blacklist dangerous operations with compliance settings

mcp-http-bridge --spec ./api.yaml --disallowed-tools "deleteUser,deletePost" \
--cascade 'compliance_level=strict!' --cascade '@*:require_mfa=true!' \
--mcp-config restricted-api
`

#### With custom mappings, cascade parameters, and logging
`bash


Generate and use custom mappings with debug logging and cascade parameters

mcp-http-bridge --spec ./api.yaml --generate-mappings ./custom-mappings.json

Edit the mappings file as needed...

mcp-http-bridge --spec ./api.yaml --mappings-file ./custom-mappings.json --log debug.log \
--cascade 'environment=staging!' --cascade 'debug_mode=true' \
--mcp-config custom-api

Full-featured setup with filtering, mappings, cascade, and logging

mcp-http-bridge --spec ./api.yaml \
--auth-file ~/.config/api-token.txt \
--allowed-tools "getUser,createUser,updateUser" \
--mappings-file ./user-mappings.json \
--cascade-file ./production-cascade.yaml \
--cascade '%PROFILE:production' \
--cascade 'deployment_id=${ENV.DEPLOYMENT_ID}!' \
--log production.log \
--rate-limit 10 \
--retries 3 \
--validate-responses \
--mcp-config production-user-api
`

#### Discovery and testing workflow with cascade parameters
`bash


1. Discover all available tools

mcp-http-bridge --spec ./api.yaml --discover

2. Test specific endpoints with cascade parameters

mcp-http-bridge --spec ./api.yaml --auth-file ./token.txt \
--cascade 'user_id=test-123!' --cascade 'environment=testing!' \
--invoke getUser --param id=1

3. Generate mappings and cascade configuration for customization

mcp-http-bridge --spec ./api.yaml --generate-mappings ./mappings.json
echo 'global:
user_id: { value: "${USER_ID}", fixed: true }
tenant_id: { value: "${TENANT_ID}", fixed: true }' > cascade.yaml

4. Deploy with filtering, custom mappings, and cascade parameters

mcp-http-bridge --spec ./api.yaml \
--auth-file ./token.txt \
--mappings-file ./mappings.json \
--cascade-file ./cascade.yaml \
--cascade 'deployment_env=production!' \
--allowed-tools "getUser,createUser" \
--mcp-config final-api
`

#### With rate limiting and retries
`bash


Limit to 5 requests per second with 5 retries


mcp-http-bridge --spec ./api.yaml --rate-limit 5 --retries 5 --timeout 10000 --mcp-config robust-api
`

$3

The auth file approach enables seamless token rotation:

`bash


Start with initial token

echo "Bearer token-v1" > api-token.txt
mcp-http-bridge --spec ./api.yaml --auth-file ./api-token.txt &

Later, rotate the token without stopping the server

echo "Bearer token-v2" > api-token.txt

Next API call will automatically use the new token!

You can even automate this with a cron job or external system

echo "Bearer $(get-fresh-token-from-vault)" > api-token.txt
`

🏗️ Development

`bash


Clone the repository

git clone https://github.com/your-username/mcp-http-bridge.git
cd mcp-http-bridge

Install dependencies

npm install

Build the project

npm run build

Run tests

npm test
``

📝 Requirements

- Node.js >= 18.0.0
- OpenAPI 3.0+ specification
- MCP-compatible client (Claude Desktop, etc.)

📄 License

MIT License

🔗 Related

- Model Context Protocol
- MCP TypeScript SDK
- Claude Desktop
- OpenAPI Specification