Pangolin
MCP server that exposes all Pangolin API endpoints as tools (with a READ_ONLY mode ๐ฎโ๐จ), enabling AI assistants to manage your Pangolin infrastructure including organizations, sites, resources, roles, users, and more
Ask AI about Pangolin
Powered by Claude ยท Grounded in docs
I know everything about Pangolin. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP Pangolin
A Model Context Protocol (MCP) server that exposes your Pangolin Integration API to Claude and other MCP-compatible AI assistants.
Sponsors
|
France-Nuage Sovereign French cloud paired with self-hosted tunnels. EU end-to-end. |
![]() Hook0 Self-hosted Webhooks-as-a-Service behind your Pangolin tunnels. |
Natalia Self-host your stack, let Natalia answer customer calls 24/7. |
Netir Hire vetted French freelance self-hosting infra experts. |
|
NoBullshitConseil Tech advisory without the bullshit. Infra & sovereignty strategy. |
Qualneo Qualiopi LMS you can self-host. 32 indicators wired in. |
![]() Recapro Sovereign AI meeting notes hosted behind your own tunnels. |
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_ONLYenvironment 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:
- Load the OpenAPI specification
- Generate tool definitions for all endpoints
- 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
| Variable | Description | Required |
|---|---|---|
PANGOLIN_API_KEY | API key for Bearer token authentication | Yes |
PANGOLIN_BASE_URL | Base URL for the Pangolin API | Yes |
PANGOLIN_OPENAPI_FILE | Path to OpenAPI specification file | Yes* |
PANGOLIN_OPENAPI_JSON | Inline OpenAPI specification JSON | Yes* |
PANGOLIN_READ_ONLY | Set to true to enable read-only mode | No |
*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
| Tool | Description |
|---|---|
orgs | List all organizations |
org_by_orgId | Get an organization by ID |
create_org | Create a new organization |
update_org_by_orgId | Update an organization |
delete_org_by_orgId | Delete an organization |
Sites
| Tool | Description |
|---|---|
org_by_orgId_sites | List all sites in an organization |
site_by_siteId | Get a site by ID |
create_org_by_orgId_site | Create a new site |
update_site_by_siteId | Update a site |
delete_site_by_siteId | Delete a site |
Resources
| Tool | Description |
|---|---|
org_by_orgId_resources | List resources for an organization |
resource_by_resourceId | Get a resource by ID |
create_org_by_orgId_resource | Create a resource |
update_resource_by_resourceId | Update a resource |
delete_resource_by_resourceId | Delete a resource |
Site Resources
| Tool | Description |
|---|---|
org_by_orgId_site_resources | List all site resources for an organization |
site_resource_by_siteResourceId | Get a specific site resource |
create_org_by_orgId_site_resource | Create a new site resource |
update_site_resource_by_siteResourceId | Update a site resource |
delete_site_resource_by_siteResourceId | Delete a site resource |
Targets
| Tool | Description |
|---|---|
resource_by_resourceId_targets | List targets for a resource |
target_by_targetId | Get a target |
create_resource_by_resourceId_target | Create a target |
update_target_by_targetId | Update a target |
delete_target_by_targetId | Delete a target |
Users
| Tool | Description |
|---|---|
org_by_orgId_users | List users in an organization |
org_by_orgId_user_by_userId | Get a user in an organization |
create_org_by_orgId_user | Create an organization user |
update_org_by_orgId_user_by_userId | Update a user |
delete_org_by_orgId_user_by_userId | Remove a user from an organization |
Roles
| Tool | Description |
|---|---|
org_by_orgId_roles | List roles in an organization |
role_by_roleId | Get a role |
create_org_by_orgId_role | Create a role |
delete_role_by_roleId | Delete a role |
Clients
| Tool | Description |
|---|---|
org_by_orgId_clients | List all clients for an organization |
client_by_clientId | Get a client by ID |
create_org_by_orgId_client | Create a new client |
update_client_by_clientId | Update a client |
delete_client_by_clientId | Delete a client |
Identity Providers
| Tool | Description |
|---|---|
idp | List all identity providers |
idp_by_idpId | Get an IDP by ID |
create_idp_oidc | Create an OIDC IdP |
update_idp_by_idpId_oidc | Update an OIDC IdP |
delete_idp_by_idpId | Delete an IDP |
API Keys
| Tool | Description |
|---|---|
org_by_orgId_api_keys | List all API keys for an organization |
create_org_by_orgId_api_key | Create a new API key |
delete_org_by_orgId_api_key_by_apiKeyId | Delete an API key |
Access Tokens
| Tool | Description |
|---|---|
org_by_orgId_access_tokens | List all access tokens in an organization |
resource_by_resourceId_access_tokens | List access tokens for a resource |
update_resource_by_resourceId_access_token | Generate a new access token |
delete_access_token_by_accessTokenId | Delete an access token |
Domains
| Tool | Description |
|---|---|
org_by_orgId_domains | List all domains for an organization |
org_by_orgId_domain_by_domainId | Get a domain by ID |
org_by_orgId_domain_by_domainId_dns_records | Get DNS records for a domain |
Blueprints
| Tool | Description |
|---|---|
org_by_orgId_blueprints | List all blueprints for an organization |
org_by_orgId_blueprint_by_blueprintId | Get a blueprint by ID |
create_org_by_orgId_blueprint | Apply a blueprint |
Logs
| Tool | Description |
|---|---|
org_by_orgId_logs_request | Query the request audit log |
org_by_orgId_logs_analytics | Query request audit analytics |
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"
- Make sure your OpenAPI specification file is valid JSON
- Check that the file path is correct
- Try using absolute paths for the
--openapiargument
"401 Unauthorized" errors
- Verify your API key is correct
- Check that the API key has sufficient permissions
- Ensure the API key is being passed correctly (via
--api-keyorPANGOLIN_API_KEYenv var)
"Connection refused" or timeouts
- Verify your Pangolin instance is accessible
- Check for firewalls or VPN requirements
- Ensure the
--base-urlincludes the correct protocol (https://) and API version path (/v1)
Write operations blocked
If you're seeing "Write operation not allowed in read-only mode":
- Check if
PANGOLIN_READ_ONLYenvironment variable is set totrue - Remove the
--read-onlyflag if you need write access - Verify your API key has write permissions on the Pangolin instance
Security Considerations
- Read-Only Mode: Use
PANGOLIN_READ_ONLY=truein 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


