Portkey Mcp Server

portkey-mcp-server

A Model Context Protocol (MCP) server implementation for Portkey. This application serves as a bridge for connecting various AI tools and services to Portkey through the Model Context Protocol.

Table of Contents

• [Supported MCP Features](#supported-mcp-features)
• [Tools](#tools)
• [Installation](#installation)
• [Docker](#docker)
• [Binary](#binary)
• [From Source](#from-source)
• [Configuration](#configuration)
• [Usage](#usage)
• [With Cursor IDE](#with-cursor-ide)
• [With Claude Desktop](#with-claude-desktop)
• [Manual SSE Requests](#manual-sse-requests)
• [Contributing](#contributing)
• [License](#license)

Supported MCP Features

Tools

• prompt_create
• prompt_render
• prompts_list

Installation

Quick Start: For immediate integration with AI tools, jump directly to the [Cursor IDE](#with-cursor-ide) or [Claude Desktop](#with-claude-desktop) usage sections. These provide ready-to-use setup instructions for each tool.

Docker

The easiest way to get started is with the pre-built Docker image from Docker Hub:

# Run the container with the latest image (PORTKEY_API_KEY is required)
docker run -p 8080:8080 \
  -e TRANSPORT=sse \
  -e TRANSPORT_SSE_ADDRESS=:8080 \
  -e PORTKEY_API_KEY=your-api-key \
  ericmccaleb/portkey-mcp-server:latest

You can also build and run it locally using the Make targets:

# Clone the repository
git clone https://github.com/rvoh-emccaleb/portkey-mcp-server.git
cd portkey-mcp-server

# Build the Docker image locally (optional)
make docker-build

# Run the container (PORTKEY_API_KEY is required)
make docker-run PORTKEY_API_KEY=your-api-key

# Run with additional non-default settings
make docker-run PORT=9000 TRANSPORT=sse PORTKEY_API_KEY=your-api-key

You can also use the Docker commands directly:

# From repo root

# Build the Docker image
docker build --build-arg APP_VERSION=$(git rev-parse --short HEAD) -t portkey-mcp-server .

# Run in SSE mode (HTTP server)
docker run -p 8080:8080 \
  -e TRANSPORT=sse \
  -e TRANSPORT_SSE_ADDRESS=:8080 \
  -e PORTKEY_API_KEY=your-api-key \
  portkey-mcp-server

Binary

To build a standalone binary:

# From repo root
make build

This will create a binary named portkey-mcp-server in the root directory that you can execute directly.

To run the binary, you'll need to provide the required environment variables:

# From repo root

# Run in SSE mode (HTTP server)
PORTKEY_API_KEY=your-api-key \
TRANSPORT=sse \
TRANSPORT_SSE_ADDRESS=:8080 \
./portkey-mcp-server

# Run in stdio mode
PORTKEY_API_KEY=your-api-key \
TRANSPORT=stdio \
./portkey-mcp-server

From Source

To run the app directly with Go tooling:

# From repo root
go run -ldflags="-X main.appVersion=$(git rev-parse --short HEAD)" cmd/portkey-mcp-server/main.go

Configuration

The server supports different transport configurations:

• stdio (Standard Input/Output) transport for command-line interfaces
• sse (Server-Sent Events) transport for HTTP-based communication

Configuration is handled through environment variables loaded at startup. [.env.example](./.env.example) can be used as a reference, but the source-of-truth is always the [config package](./internal/config/).

For running outside of Docker, you can configure the application by creating a .env file based on the variables expected by the [config package](./internal/config/). For Docker, environment variables should be set by other means.

Usage

With Cursor IDE

Create a .cursor/mcp.json file in your home directory (for global-level config) or in your repo root (for project-level config).

Using stdio Mode

With Docker (using the Docker Hub image):

{
  "mcpServers": {
    "Portkey": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "PORTKEY_API_KEY",
        "-e", "TRANSPORT",
        "ericmccaleb/portkey-mcp-server:latest"
      ],
      "env": {
        "PORTKEY_API_KEY": "your-api-key",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Or with binary:

{
  "mcpServers": {
    "Portkey": {
      "command": "/path/to/portkey-mcp-server-binary",
      "env": {
        "PORTKEY_API_KEY": "your-api-key",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Using SSE Mode

If the server is already running locally, or elsewhere:

{
  "mcpServers": {
    "Portkey": {
      "url": "http://localhost:8080/sse"
    }
  }
}

With Claude Desktop

Claude Desktop only supports stdio mode. Create a claude_desktop_config.json file in:

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

With Docker (using the Docker Hub image):

{
  "mcpServers": {
    "Portkey": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "PORTKEY_API_KEY",
        "-e", "TRANSPORT",
        "ericmccaleb/portkey-mcp-server:latest"
      ],
      "env": {
        "PORTKEY_API_KEY": "your-api-key",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Or with binary:

{
  "mcpServers": {
    "Portkey": {
      "command": "/path/to/portkey-mcp-server-binary",
      "env": {
        "PORTKEY_API_KEY": "your-api-key",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Manual SSE Requests

When running in SSE mode, you can access the server using HTTP requests. Following the MCP protocol requires these steps:

# 1. First establish the SSE connection to get a session
curl http://localhost:8080/sse
# This will return something like:
# event: endpoint
# data: /message?sessionId=abc123

# 2. Initialize the session (using the URL from #1, above)
curl -X POST "http://localhost:8080/message?sessionId=abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": {
        "name": "curl-client",
        "version": "1.0.0"
      },
      "capabilities": {}
    }
  }'

# 3. Now you can make tool calls
curl -X POST "http://localhost:8080/message?sessionId=abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "call_tool",
    "params": {
      "name": "prompt_render", 
      "arguments": {
        "prompt_id": "your_prompt_id",
        "variables": {
            "your_prompt_variable": "some_value"
        }
      }
    }
  }'

> Note: The SSE connection in step 1 must remain open during your session. Run it in a separate terminal window and do not close it until you're done with the session.

Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get started.

License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rvoh-emccaleb
• Source: rvoh-emccaleb/portkey-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.