invoke-mcp

<p align="center"> <img src="https://img.shields.io/badge/MCP-Server-blue?style=for-the-badge" alt="MCP Server" /> <img src="https://img.shields.io/badge/Node.js-18+-green?style=for-the-badge&logo=node.js" alt="Node.js 18+" /> <img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="MIT License" /> </p> <h1 align="center">Invoke</h1> <p align="center"> <strong>Universal API-to-tool bridge for Claude</strong><br> Register any API. Invoke it naturally. </p> <p align="center"> <a href="#-quick-start">Quick Start</a> • <a href="#-features">Features</a> • <a href="#-how-it-works">How It Works</a> • <a href="#-configuration">Configuration</a> • <a href="#-cli-commands">CLI Commands</a> • <a href="#-mcp-tools">MCP Tools</a> </p>

---

What is Invoke?

Invoke is an MCP (Model Context Protocol) server that lets Claude access any REST API. When Claude needs data it doesn't have, it automatically researches the API, registers it, and makes the call.

User: "What's Apple stock worth today?"

Claude: [discovers no stock API configured]
Claude: [researches Alpha Vantage API documentation]
Claude: [registers the API configuration]
Claude: "Please add your API key: invoke add ALPHAVANTAGE_API_KEY <key>"

User: [adds key]

Claude: [calls API]
Claude: "AAPL is currently trading at $187.44, up 1.2% today."

---

🚀 Quick Start

Install

git clone https://github.com/tarann26/invoke.git
cd invoke
npm install && npm run build
./install-global.sh

The install script will:

• Create config directories
• Set up the invoke CLI command
• Configure Claude Desktop and Claude Code

Add Your First API Key

invoke add OPENAI_API_KEY sk-...

Restart Claude

Restart Claude Desktop or Claude Code to load the Invoke MCP server.

Ask Claude for Data

Just ask naturally. Claude will discover, research, and register APIs as needed:

• "What's the weather in Tokyo?"
• "Get me the latest news about AI"
• "What's Bitcoin trading at?"

---

✨ Features

| Feature | Description | |---------|-------------| | Dynamic API Discovery | Claude researches and registers APIs on first use | | Universal API Support | Any REST API works — LLMs, data APIs, internal services | | Multi-Key Support | Multiple keys per API (dev/prod/project) with runtime selection | | Request Caching | Cache API responses with configurable TTL to reduce costs | | Health Dashboard | Monitor API health, latency, and success rates | | Workflows | Chain multiple API calls with data passing between steps | | Multi-LLM | Let Claude talk to GPT-4, Gemini, Mistral, and more | | Full Logging | Every API call logged with latency, status, and errors | | Secure by Default | API keys stay local, sensitive data masked in logs |

---

🔄 How It Works

Invoke uses dynamic API discovery instead of static templates. When you ask Claude for data:

1. Discover — Claude checks if an API is configured for that data type
2. Research — If not found, Claude searches the API's documentation
3. Register — Claude constructs and saves the API configuration
4. Request Key — Claude asks you to add the API key (if required)
5. Execute — Claude makes the API call and returns the data

This means you don't need to pre-configure APIs. Just ask for data, and Claude handles the rest.

Important: Model Selection

For LLM APIs (OpenAI, Anthropic, etc.), Claude will always ask which model to use before making calls. Different models have different pricing, so Claude never assumes a default.

---

📁 Configuration

Directory Structure

~/.config/invoke/
└── configs/
    └── *.yaml            # Auto-generated API configs

~/.invoke/
├── secrets.yaml          # API keys (chmod 600)
└── logs/
    ├── api-calls.jsonl   # JSON logs
    └── api-calls.log     # Human-readable logs

Config Format

API configs are auto-generated by Claude, but you can also create them manually:

version: "1"

apis:
  - name: weather
    description: Weather data API
    base_url: https://api.openweathermap.org/data/2.5
    auth:
      type: api_key
      location: query
      name: appid
      env_var: OPENWEATHER_API_KEY
    endpoints:
      - name: current
        description: Get current weather for a city
        path: /weather
        method: GET
        params:
          - name: q
            description: City name
            type: string
            required: true
            location: query

Workflow Config

workflows:
  - name: morning_briefing
    description: Get weather and news for a city
    input_schema:
      city:
        type: string
        required: true
    steps:
      - id: weather
        tool: weather__current
        param_mappings:
          q: "$input.city"

      - id: news
        tool: newsapi__headlines
        param_mappings:
          q: "$input.city"
        condition: "$steps.weather.success"

Authentication Types

<details> <summary><strong>API Key (Header or Query)</strong></summary>

auth:
  type: api_key
  location: header  # or "query"
  name: X-API-Key
  env_var: MY_API_KEY

</details> <details> <summary><strong>Bearer Token</strong></summary>

auth:
  type: bearer
  env_var: MY_TOKEN

</details> <details> <summary><strong>Basic Auth</strong></summary>

auth:
  type: basic
  username_env: MY_USERNAME
  password_env: MY_PASSWORD

</details>

Multi-Key Support

Invoke supports multiple keys per API for different environments (dev/prod) or projects:

# Add keys with aliases
invoke add OPENAI_API_KEY sk-default-key           # Default key
invoke add OPENAI_API_KEY:dev sk-dev-key           # Development
invoke add OPENAI_API_KEY:prod sk-prod-key         # Production
invoke add OPENAI_API_KEY:project_x sk-proj-key    # Project-specific

# View configured aliases
invoke keys --aliases

How it works:

1. CLI Usage — Use --key-alias to select which key to use:

   invoke call openai__chat --key-alias prod --param model=gpt-4o
   

2. MCP Usage — When aliases exist, Claude sees a __key_alias parameter on authenticated tools:

   Claude: [calls openai__chat({ model: "gpt-4o", __key_alias: "prod", ... })]
   

3. Listing Aliases — Claude can use invoke__select_key to see available aliases:

   Claude: [calls invoke__select_key({ env_var: "OPENAI_API_KEY" })]
           → { aliases: ["dev", "prod", "project_x"], has_default: true }
   

Secrets file format:

# ~/.invoke/secrets.yaml
secrets:
  # Simple format (single key)
  WEATHER_API_KEY: "abc123"

  # Extended format (multiple keys)
  OPENAI_API_KEY:
    default: "sk-default..."
    aliases:
      dev: "sk-dev..."
      prod: "sk-prod..."

---

⌨️ CLI Commands

Key Management

invoke add OPENAI_API_KEY                  # Secure: prompts for hidden input
invoke add OPENAI_API_KEY sk-...           # Add default key (visible in history)
invoke add OPENAI_API_KEY:dev              # Add alias with hidden input
invoke add OPENAI_API_KEY:prod sk-prod-... # Add 'prod' alias
invoke add MY_KEY --expires 2025-12-31     # Key with expiration date
invoke add MY_KEY --env prod               # Mark as production key
invoke keys                                # List all keys
invoke keys --aliases                      # Show keys with aliases
invoke keys --show                         # Show masked values
invoke remove OPENAI_API_KEY               # Remove entire key
invoke remove OPENAI_API_KEY:dev           # Remove specific alias
invoke rotate OPENAI_API_KEY               # Rotate key (keeps old as :previous)
invoke export                              # Export all keys to shell
invoke export OPENAI_API_KEY               # Export single key (default)
invoke export OPENAI_API_KEY:prod          # Export specific alias
invoke export OPENAI_API_KEY --value       # Output raw value (for piping)

Secure Hidden Input — When you omit the value, invoke prompts for hidden input:

$ invoke add OPENAI_API_KEY

Adding OPENAI_API_KEY with hidden input (value won't appear in shell history)

Enter value for OPENAI_API_KEY: ••••••••••••••••••••
Confirm value: ••••••••••••••••••••

✓ Added OPENAI_API_KEY

This keeps your API keys out of shell history and any monitoring tools.

Secure API Calls

Make API calls directly via CLI (keys never exposed to caller):

invoke call openai__chat --param model=gpt-4o-mini --param 'messages=[{"role":"user","content":"Hi"}]'
invoke call openai__chat --key-alias prod --param model=gpt-4o  # Use specific key alias

API Management

invoke list                           # List all APIs and endpoints
invoke config                         # Show config paths and status

Caching

invoke cache                          # View cache statistics
invoke cache --clear                  # Clear all cache
invoke cache --clear weather          # Clear cache for specific API

Workflows

invoke workflow --list                # List available workflows
invoke workflow morning_briefing --input '{"city": "London"}'

Logs

invoke logs                           # View recent API calls
invoke logs --lines 50                # View last 50 entries
invoke logs --follow                  # Follow logs in real-time

Security & Compliance

invoke security                       # Security status overview
invoke security --expiring            # Show keys expiring in 30 days
invoke security --rate-limits         # Show rate limit status per key
invoke audit                          # View audit log (SOC2 compliance)
invoke audit --type api_call          # Filter audit by event type
invoke rotate OPENAI_API_KEY          # Rotate key, keep old as :previous

All Commands

| Command | Description | |---------|-------------| | invoke add <KEY>[:<alias>] [value] | Add key (prompts for hidden input if no value) | | invoke remove <KEY>[:<alias>] | Remove an API key or specific alias | | invoke rotate <KEY> | Rotate key, keeping old as :previous alias | | invoke keys [--aliases] [--show] | List all configured keys | | invoke list | List all APIs and endpoints | | invoke logs | View recent API calls | | invoke config | Show configuration status | | invoke cache [--clear] | Cache statistics and management | | invoke workflow | List or run workflows | | invoke export [KEY[:<alias>]] | Export all keys or a single key/alias | | invoke call <api__endpoint> [--key-alias] | Make API call directly (secure mode) | | invoke security | Security status and key expiration | | invoke audit | View audit log for compliance | | invoke help | Show help message |

---

🔧 MCP Tools

These tools are available to Claude when connected to Invoke as an MCP server:

| Tool | Description | |------|-------------| | invoke__discover | Search configured APIs by keyword or capability | | invoke__research_api | Get guidance on researching a new API | | invoke__register_api | Register a new API from structured config | | invoke__select_key | List available key aliases for runtime selection | | invoke__logs | View recent API calls and statistics | | invoke__status | View health status of all APIs | | invoke__cache | Manage request cache (stats, clear) | | invoke__workflow | Execute workflows (named or ad-hoc) | | workflow__* | Auto-generated tools for each defined workflow | | {api}__{endpoint} | Auto-generated tools for each API endpoint |

Dynamic API Registration Flow

User: "What's the weather in Paris?"

Claude: [calls invoke__discover("weather")]
        → No APIs found

Claude: [calls invoke__research_api({ api_name: "openweathermap", api_type: "data" })]
        → Gets guidance on what to research

Claude: [searches "openweathermap API documentation"]
        → Reads the docs

Claude: [calls invoke__register_api({ name: "weather", base_url: "...", ... })]
        → Config saved to ~/.config/invoke/configs/weather.yaml

Claude: "I've registered the OpenWeatherMap API. Please add your key:
        invoke add OPENWEATHER_API_KEY <your-key>"

User: [adds key]

Claude: [calls weather__current({ q: "Paris" })]
        → Returns weather data

Claude: "It's currently 12°C and cloudy in Paris."

---

🗑 Uninstall

./uninstall.sh

Or manually:

rm -rf ~/.local/share/invoke
rm -f ~/.local/bin/invoke ~/.local/bin/invoke-server
# Optionally remove configs:
rm -rf ~/.invoke ~/.config/invoke

---

🔧 Development

# Watch mode
npm run dev

# Build
npm run build

# Type checking
npm run typecheck

Project Structure

src/
├── index.ts          # MCP server entry point
├── cli.ts            # CLI entry point
├── config.ts         # Configuration loading
├── executor.ts       # API execution engine
├── logger.ts         # Request logging
├── cache.ts          # Request caching with TTL
├── health.ts         # Health dashboard
├── wizard.ts         # Setup wizard
├── register.ts       # API registration
├── workflow.ts       # Workflow execution engine
└── types.ts          # TypeScript types and Zod schemas

---

📄 License

MIT

---

<p align="center"> _{Built for <a href="https://claude.ai">Claude</a> with the <a href="https://modelcontextprotocol.io">Model Context Protocol</a>} </p>