Tyk API Management

What is tyk-dashboard-mcp?

tyk-dashboard-mcp is a tool that creates dynamic Model Context Protocol (MCP) servers from OpenAPI/Swagger specifications. This enables seamless integration of REST APIs with AI assistants, effectively turning any API into an AI-accessible tool. It allows AI assistants to interact with APIs defined by OpenAPI specifications.

How to use tyk-dashboard-mcp?

The primary way to use tyk-dashboard-mcp is by configuring your AI assistant to run it directly as an MCP tool. Here are examples for setting it up with Claude Desktop, Cursor, and Vercel AI SDK:

Setting Up in Claude Desktop

1. Ensure Node.js is installed.
2. Open Claude Desktop and navigate to Settings > Developer.
3. Edit the configuration file (claude_desktop_config.json) and add the mcpServers configuration, specifying the command and arguments for api-to-mcp (e.g., --spec for your OpenAPI specification).
4. Restart Claude Desktop.

Setting Up in Cursor

1. Create a configuration file (.cursor/mcp.json or ~/.cursor/mcp.json).
2. Add the servers configuration, similar to Claude Desktop, specifying the command and arguments for api-to-mcp.
3. Restart Cursor or reload the window.

Using with Vercel AI SDK

1. Import experimental_createMCPClient and Experimental_StdioMCPTransport from ai.
2. Initialize an MCP client with Experimental_StdioMCPTransport, providing the command and arguments for api-to-mcp.
3. Use mcpClient.tools() to retrieve tools and pass them to your AI model (e.g., generateText from @ai-sdk/google).

Configuration

Configuration can be managed via environment variables, command-line options, or a JSON configuration file. Command-line options have the highest precedence, followed by environment variables, and then the JSON configuration file.

• Command Line Options: Use flags like --spec, --overlays, --whitelist, --targetUrl, --headers, and --disableXMcp.
• Environment Variables: Set variables like OPENAPI_SPEC_PATH, OPENAPI_OVERLAY_PATHS, TARGET_API_BASE_URL, MCP_WHITELIST_OPERATIONS, API_KEY, etc.
• JSON Configuration: Create a config.json or openapi-mcp.json file with settings like spec, overlays, targetUrl, whitelist, apiKey, etc.

Key Features of tyk-dashboard-mcp

• Dynamic OpenAPI Spec Loading: Load OpenAPI specifications from files or HTTP/HTTPS URLs.
• OpenAPI Overlays Support: Apply OpenAPI Overlays from files or URLs.
• Customizable Mapping: Map OpenAPI operations to MCP tools.
• Advanced Operation Filtering: Filter operations using glob patterns for operationId and URL paths.
• Comprehensive Parameter Handling: Preserve format and location metadata for parameters.
• API Authentication Handling: Manage API authentication.
• OpenAPI Metadata Utilization: Use OpenAPI metadata (title, version, description) to configure the MCP server.
• Hierarchical Description Fallbacks: Provides fallbacks for descriptions (operation description → operation summary → path summary).
• Custom HTTP Headers: Support for custom HTTP headers via environment variables and CLI.
• X-MCP Header: Includes an X-MCP header for API request tracking and identification.
• Custom x-mcp Extensions: Support for custom x-mcp extensions at the path level to override tool names and descriptions.

Use Cases of tyk-dashboard-mcp

• Integrating APIs with AI Assistants: Easily expose your REST APIs to AI assistants like Claude Desktop and Cursor.
• Automated API Interaction: Enable AI models to programmatically interact with your APIs for various tasks.
• Custom Tool Creation: Create branded and customized MCPs for specific APIs or services.
• Development and Testing: Facilitate development and testing of AI applications that rely on API interactions.
• Vercel AI SDK Integration: Seamlessly integrate API tools into JavaScript/TypeScript applications using the Vercel AI SDK.

FAQ from tyk-dashboard-mcp

Q: Can I customize my own version of tyk-dashboard-mcp?

A: Yes, you can fork the repository, add your OpenAPI specs, configure default settings in config.json, update package.json to include your specs, and then publish your customized package to npm. The GitHub Actions workflow can automate this process.

Q: How can I ensure my OpenAPI specs are bundled with my published package?

A: Ensure that the files field in your package.json includes dist/**/*, config.json, specs/**/*, and README.md.

Q: What is the precedence for configuration settings?

A: Command-line options have the highest precedence, followed by environment variables, and then the JSON configuration file.

OpenAPI to MCP Server

A tool that creates MCP (Model Context Protocol) servers from OpenAPI/Swagger specifications, enabling AI assistants to interact with your APIs. Create your own branded and customized MCPs for specific APIs or services.

Overview

This project creates a dynamic MCP server that transforms OpenAPI specifications into MCP tools. It enables seamless integration of REST APIs with AI assistants via the Model Context Protocol, turning any API into an AI-accessible tool.

Features

• Dynamic loading of OpenAPI specs from file or HTTP/HTTPS URLs
• Support for OpenAPI Overlays loaded from files or HTTP/HTTPS URLs
• Customizable mapping of OpenAPI operations to MCP tools
• Advanced filtering of operations using glob patterns for both operationId and URL paths
• Comprehensive parameter handling with format preservation and location metadata
• API authentication handling
• OpenAPI metadata (title, version, description) used to configure the MCP server
• Hierarchical description fallbacks (operation description → operation summary → path summary)
• Custom HTTP headers support via environment variables and CLI
• X-MCP header for API request tracking and identification
• Support for custom x-mcp extensions at the path level to override tool names and descriptions

Using with AI Assistants

This tool creates an MCP server that allows AI assistants to interact with APIs defined by OpenAPI specifications. The primary way to use it is by configuring your AI assistant to run it directly as an MCP tool.

Setting Up in Claude Desktop

1. Ensure you have Node.js installed on your computer

2. Open Claude Desktop and navigate to Settings > Developer

3. Edit the configuration file (or it will be created if it doesn't exist):

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

4. Add this configuration (customize as needed):

{
  "mcpServers": {
    "api-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--spec",
        "https://petstore3.swagger.io/api/v3/openapi.json"
      ],
      "enabled": true
    }
  }
}

5. Restart Claude Desktop
6. You should now see a hammer icon in the chat input box. Click it to access your API tools.

Customizing the Configuration

You can adjust the args array to customize your MCP server with various options:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--spec",
        "./path/to/your/openapi.json",
        "--overlays",
        "./path/to/overlay.json,https://example.com/api/overlay.json",
        "--whitelist",
        "getPet*,POST:/users/*",
        "--targetUrl",
        "https://api.example.com"
      ],
      "enabled": true
    }
  }
}

Setting Up in Cursor

1. Create a configuration file in one of these locations:

   • Project-specific: .cursor/mcp.json in your project directory
   • Global: ~/.cursor/mcp.json in your home directory

2. Add this configuration (adjust as needed for your API):

{
  "servers": [
    {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--spec",
        "./path/to/your/openapi.json"
      ],
      "name": "My API Tools"
    }
  ]
}

3. Restart Cursor or reload the window

Using with Vercel AI SDK

You can also use this MCP server directly in your JavaScript/TypeScript applications using the Vercel AI SDK's MCP client:

import { experimental_createMCPClient } from 'ai';
import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';
import { generateText } from 'ai';
import { createGoogleGenerativeAI } from '@ai-sdk/google';

// Initialize the Google Generative AI provider
const google = createGoogleGenerativeAI({
  apiKey: process.env.GOOGLE_API_KEY, // Set your API key in environment variables
});
const model = google('gemini-2.0-flash');

// Create an MCP client with stdio transport
const mcpClient = await experimental_createMCPClient({
  transport: {
    type: 'stdio',
    command: 'npx', // Command to run the MCP server
    args: ['-y', '@tyktechnologies/api-to-mcp', '--spec', 'https://petstore3.swagger.io/api/v3/openapi.json'], // OpenAPI spec
    env: {
      // You can set environment variables here
      // API_KEY: process.env.YOUR_API_KEY,
    },
  },
});

async function main() {
  try {
    // Retrieve tools from the MCP server
    const tools = await mcpClient.tools();

    // Generate text using the AI SDK with MCP tools
    const { text } = await generateText({
      model,
      prompt: 'List all available pets in the pet store using the API.',
      tools, // Pass the MCP tools to the model
    });

    console.log('Generated text:', text);
  } catch (error) {
    console.error('Error:', error);
  } finally {
    // Always close the MCP client to release resources
    await mcpClient.close();
  }
}

main();

Configuration

Configuration is managed via environment variables, command-line options, or a JSON configuration file:

Command Line Options

# Start with specific OpenAPI spec file
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json

# Apply overlays to the spec
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --overlays=./path/to/overlay.json,https://example.com/api/overlay.json

# Include only specific operations (supports glob patterns)
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --whitelist="getPet*,POST:/users/*"

# Specify target API URL
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --targetUrl=https://api.example.com

# Add custom headers to all API requests
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --headers='{"X-Api-Version":"1.0.0"}'

# Disable the X-MCP header
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --disableXMcp

Environment Variables

You can set these in a .env file or directly in your environment:

• OPENAPI_SPEC_PATH: Path to OpenAPI spec file
• OPENAPI_OVERLAY_PATHS: Comma-separated paths to overlay JSON files
• TARGET_API_BASE_URL: Base URL for API calls (overrides OpenAPI servers)
• MCP_WHITELIST_OPERATIONS: Comma-separated list of operation IDs or URL paths to include (supports glob patterns like getPet* or GET:/pets/*)
• MCP_BLACKLIST_OPERATIONS: Comma-separated list of operation IDs or URL paths to exclude (supports glob patterns, ignored if whitelist used)
• API_KEY: API Key for the target API (if required)
• SECURITY_SCHEME_NAME: Name of the security scheme requiring the API Key
• SECURITY_CREDENTIALS: JSON string containing security credentials for multiple schemes
• CUSTOM_HEADERS: JSON string containing custom headers to include in all API requests
• HEADER_*: Any environment variable starting with HEADER_ will be added as a custom header (e.g., HEADER_X_API_Version=1.0.0 adds the header X-API-Version: 1.0.0)
• DISABLE_X_MCP: Set to true to disable adding the X-MCP: 1 header to all API requests
• CONFIG_FILE: Path to a JSON configuration file

JSON Configuration

You can also use a JSON configuration file instead of environment variables or command-line options. The MCP server will look for configuration files in the following order:

1. Path specified by --config command-line option
2. Path specified by CONFIG_FILE environment variable
3. config.json in the current directory
4. openapi-mcp.json in the current directory
5. .openapi-mcp.json in the current directory

Example JSON configuration file:

{
  "spec": "./path/to/openapi-spec.json",
  "overlays": "./path/to/overlay1.json,https://example.com/api/overlay.json",
  "targetUrl": "https://api.example.com",
  "whitelist": "getPets,createPet,/pets/*",
  "blacklist": "deletePet,/admin/*",
  "apiKey": "your-api-key",
  "securitySchemeName": "ApiKeyAuth",
  "securityCredentials": {
    "ApiKeyAuth": "your-api-key",
    "OAuth2": "your-oauth-token"
  },
  "headers": {
    "X-Custom-Header": "custom-value",
    "User-Agent": "OpenAPI-MCP-Client/1.0"
  },
  "disableXMcp": false
}

A full example configuration file with explanatory comments is available at config.example.json in the root directory.

Configuration Precedence

Configuration settings are applied in the following order of precedence (highest to lowest):

1. Command-line options
2. Environment variables
3. JSON configuration file

Development

Installation

# Clone the repository
git clone <repository-url>
cd openapi-to-mcp-generator

# Install dependencies
npm install

# Build the project
npm run build

Local Testing

# Start the MCP server
npm start

# Development mode with auto-reload
npm run dev

Customizing and Publishing Your Own Version

You can use this repository as a base for creating your own customized OpenAPI to MCP server. This section explains how to fork the repository, customize it for your specific APIs, and publish it as a package.

Forking and Customizing

1. Fork the Repository: Fork this repository on GitHub to create your own copy that you can customize.

2. Add Your OpenAPI Specs:

   # Create a specs directory if it doesn't exist
   mkdir -p specs
   
   # Add your OpenAPI specifications
   cp path/to/your/openapi-spec.json specs/
   
   # Add any overlay files
   cp path/to/your/overlay.json specs/
   

3. Configure Default Settings: Create a custom config file that will be bundled with your package:

   # Copy the example config
   cp config.example.json config.json
   
   # Edit the config to point to your bundled specs
   # and set any default settings
   

4. Update package.json:

   {
     "name": "your-custom-mcp-server",
     "version": "1.0.0",
     "description": "Your customized MCP server for specific APIs",
     "files": [
       "dist/**/*",
       "config.json",
       "specs/**/*",
       "README.md"
     ]
   }
   

5. Ensure Specs are Bundled: The files field in package.json (shown above) ensures your specs and config file will be included in the published package.

Customizing the GitHub Workflow

The repository includes a GitHub Actions workflow for automatic publishing to npm. To customize it for your forked repo:

1. Update the Workflow Name: Edit .github/workflows/publish-npm.yaml to update the name if desired:

   name: Publish My Custom MCP Package
   

2. Set Package Scope (if needed): If you want to publish under an npm organization scope, uncomment and modify the scope line in the workflow file:

   - name: Setup Node.js
     uses: actions/setup-node@v4
     with:
       node-version: "18"
       registry-url: "https://registry.npmjs.org/"
       # Uncomment and update with your organization scope:
       scope: "@your-org"
   

3. Set Up npm Token: Add your npm token as a GitHub secret named NPM_TOKEN in your forked repository's settings.

Publishing Your Customized Package

Once you've customized the repository:

1. Create and Push a Tag:

   # Update version in package.json (optional, the workflow will update it based on the tag)
   npm version 1.0.0
   
   # Push the tag
   git push --tags
   

2. GitHub Actions will:

   • Automatically build the package
   • Update version in package.json to match the tag
   • Publish to npm with your bundled specs and config

Usage After Publication

Users of your customized package can install and use it with npm:

# Install your customized package
npm install your-custom-mcp-server -g

# Run it
your-custom-mcp-server

They can override your default settings via environment variables or command line options as described in the Configuration section.

License

MIT