Pangolin

Sponsors

Interested in sponsoring? Get in touch

Overview

This project provides an MCP server that exposes all Pangolin API endpoints as tools, enabling AI assistants to manage your Pangolin infrastructure including organizations, sites, resources, roles, users, and more.

Features

• Full coverage of Pangolin Integration API endpoints
• Read-only mode via PANGOLIN_READ_ONLY environment variable
• Bearer token authentication via PANGOLIN_API_KEY
• Automatic tool generation from OpenAPI/Swagger specification
• Support for path parameters, query parameters, and request bodies

Quick Start

Prerequisites

• Rust stable (install)
• A Pangolin instance with API access
• A Pangolin API key

1. Build the project

git clone https://github.com/FGRibreau/mcp-pangolin.git
cd mcp-pangolin
cargo build --release

2. Run the MCP server

./target/release/mcp-pangolin \
  --openapi pangolin-api.json \
  --api-key YOUR_API_KEY \
  --base-url https://your-pangolin-instance.com/v1

The server will:

1. Load the OpenAPI specification
2. Generate tool definitions for all endpoints
3. Start listening on stdin/stdout for MCP messages

Read-Only Mode

To run the server in read-only mode (only GET operations are allowed):

./target/release/mcp-pangolin \
  --openapi pangolin-api.json \
  --api-key YOUR_API_KEY \
  --base-url https://your-pangolin-instance.com/v1 \
  --read-only

Or via environment variable:

export PANGOLIN_READ_ONLY=true
./target/release/mcp-pangolin \
  --openapi pangolin-api.json \
  --api-key YOUR_API_KEY \
  --base-url https://your-pangolin-instance.com/v1

Configuration

Environment Variables

*Either PANGOLIN_OPENAPI_FILE or PANGOLIN_OPENAPI_JSON must be provided.

Claude Code

Add the following to your Claude Code MCP settings:

claude mcp add pangolin \
  --command /path/to/mcp-pangolin \
  --args "--openapi" "/path/to/pangolin-api.json" "--base-url" "https://your-pangolin-instance.com/v1" \
  --env "PANGOLIN_API_KEY=YOUR_API_KEY"

For read-only mode:

claude mcp add pangolin \
  --command /path/to/mcp-pangolin \
  --args "--openapi" "/path/to/pangolin-api.json" "--base-url" "https://your-pangolin-instance.com/v1" "--read-only" \
  --env "PANGOLIN_API_KEY=YOUR_API_KEY"

Or manually add it to your MCP settings file:

{
  "mcpServers": {
    "pangolin": {
      "command": "/path/to/mcp-pangolin",
      "args": [
        "--openapi", "/path/to/pangolin-api.json",
        "--base-url", "https://your-pangolin-instance.com/v1"
      ],
      "env": {
        "PANGOLIN_API_KEY": "YOUR_API_KEY",
        "PANGOLIN_READ_ONLY": "true"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pangolin": {
      "command": "/absolute/path/to/mcp-pangolin",
      "args": [
        "--openapi", "/absolute/path/to/pangolin-api.json",
        "--base-url", "https://your-pangolin-instance.com/v1"
      ],
      "env": {
        "PANGOLIN_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Usage Examples

Once configured, you can ask Claude questions like:

• "List all organizations in Pangolin"
• "Show me the sites for organization 'my-org'"
• "What resources are available in site 123?"
• "List all users in the organization"
• "Show me the roles configured for this resource"

And with write access (when not in read-only mode):

• "Create a new site called 'production-us'"
• "Add user john@example.com to the admin role"
• "Update the resource configuration for the API gateway"

Available Tools

The MCP server generates tools based on the Pangolin OpenAPI specification. Below are the main categories:

Organizations

Sites

Resources

Site Resources

Targets

Users

Roles

Clients

Identity Providers

API Keys

Access Tokens

Domains

Blueprints

Logs

CLI Reference

mcp-pangolin [OPTIONS] --api-key <API_KEY> --base-url <BASE_URL>

Options:
  -o, --openapi <OPENAPI>        Path to OpenAPI/Swagger JSON specification file
                                 [env: PANGOLIN_OPENAPI_FILE]

      --openapi-json <JSON>      Inline OpenAPI/Swagger JSON specification
                                 [env: PANGOLIN_OPENAPI_JSON]

  -k, --api-key <API_KEY>        Pangolin API key for authentication
                                 [env: PANGOLIN_API_KEY]

  -b, --base-url <BASE_URL>      Base URL for the Pangolin API
                                 [env: PANGOLIN_BASE_URL]

  -r, --read-only                Enable read-only mode (only GET operations)
                                 [env: PANGOLIN_READ_ONLY]

  -h, --help                     Print help
  -V, --version                  Print version

Development

# Build debug version
cargo build

# Run tests
cargo test

# Run with logging
RUST_LOG=debug ./target/debug/mcp-pangolin \
  --openapi pangolin-api.json \
  --api-key YOUR_KEY \
  --base-url https://api.example.com/v1

Running Tests

# Run all tests
cargo test

# Run read-only mode tests specifically
cargo test --test read_only_mode

# Run tests with output
cargo test -- --nocapture

Troubleshooting

"No tools available"

1. Make sure your OpenAPI specification file is valid JSON
2. Check that the file path is correct
3. Try using absolute paths for the --openapi argument

"401 Unauthorized" errors

1. Verify your API key is correct
2. Check that the API key has sufficient permissions
3. Ensure the API key is being passed correctly (via --api-key or PANGOLIN_API_KEY env var)

"Connection refused" or timeouts

1. Verify your Pangolin instance is accessible
2. Check for firewalls or VPN requirements
3. Ensure the --base-url includes the correct protocol (https://) and API version path (/v1)

Write operations blocked

If you're seeing "Write operation not allowed in read-only mode":

1. Check if PANGOLIN_READ_ONLY environment variable is set to true
2. Remove the --read-only flag if you need write access
3. Verify your API key has write permissions on the Pangolin instance

Security Considerations

• Read-Only Mode: Use PANGOLIN_READ_ONLY=true in production environments where AI assistants should only have read access
• API Key Security: Never commit API keys to version control. Use environment variables or secret management solutions
• Network Security: Always use HTTPS for the base URL

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Acknowledgments

• Built with rmcp - Rust MCP SDK
• Inspired by the Model Context Protocol specification
• Designed for Pangolin - Tunneled Reverse Proxy with Identity and Access Management