https://github.com/rvoh-emccaleb/portkey-mcp-server
MCP Server for Portkey
https://github.com/rvoh-emccaleb/portkey-mcp-server
Last synced: about 2 months ago
JSON representation
MCP Server for Portkey
- Host: GitHub
- URL: https://github.com/rvoh-emccaleb/portkey-mcp-server
- Owner: rvoh-emccaleb
- Created: 2025-04-16T20:55:59.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-04-26T00:06:22.000Z (6 months ago)
- Last Synced: 2025-04-26T01:19:25.048Z (6 months ago)
- Language: Go
- Size: 23.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-mcp-servers - **portkey-mcp-server** - MCP Server for Portkey `go` `mcp` `server` `go install rvoh-emccaleb/portkey-mcp-server@latest` (⚙️ DevOps)
- awesome-mcp-servers - **portkey-mcp-server** - MCP Server for Portkey `go` `mcp` `server` `go install rvoh-emccaleb/portkey-mcp-server@latest` (DevOps)
README
# 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`](https://portkey.ai/docs/api-reference/admin-api/control-plane/prompts/create-prompt)
- [`prompt_render`](https://portkey.ai/docs/api-reference/inference-api/prompts/render)
- [`prompts_list`](https://portkey.ai/docs/api-reference/admin-api/control-plane/prompts/list-prompts)
## 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:
```shell
# 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:
```shell
# 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:
```shell
# 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:
```shell
# 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:
```shell
# 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:
```shell
# 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):
```json
{
"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:
```json
{
"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:
```json
{
"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):
```json
{
"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:
```json
{
"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:
```shell
# 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.