MCP Integration¶

Connect Claude and other MCP clients to elluminate for interactive prompt evaluation, experiment tracking, and AI-assisted optimization workflows.

The elluminate MCP (Model Context Protocol) server exposes platform capabilities through a standardized interface, enabling LLM assistants to help you build, run, and analyze prompt evaluation experiments.

What is MCP?¶

MCP (Model Context Protocol) is an open standard that allows AI assistants to interact with external tools and data sources. The elluminate MCP server translates MCP requests into elluminate SDK calls, letting MCP clients:

Create and manage prompt templates, collections, and criteria
Run experiments and generate responses
Analyze evaluation results and identify failure patterns
Iterate on prompts based on detailed feedback

Benefits¶

Interactive Workflow Development

Build evaluation pipelines conversationally with AI assistants
Get instant feedback on experiment design and test coverage
Debug failed test cases with AI-assisted analysis

Streamlined Iteration

Quickly clone and modify resources for A/B testing
Analyze results and refine prompts in a single session
Track experiment history and performance trends

Knowledge Integration

Leverage AI assistants' understanding of your domain to generate test cases
Get suggestions for evaluation criteria and edge cases
Combine elluminate's systematic evaluation with AI reasoning capabilities

Capabilities Overview¶

The MCP server provides many tools organized by functional area:

Project Management

List organizations and projects
Create and clone projects
Switch between project contexts

Prompt Templates

Create versioned prompt templates with {{placeholders}}
List and retrieve template versions
Clone templates for A/B testing

Test Collections

Manage test case sets with multiple column types (TEXT, CONVERSATION, RAW_INPUT, CATEGORY)
Create collections from scratch or clone existing ones
Review test inputs and add new cases

Evaluation Criteria

Define binary yes/no evaluation questions
Create criterion sets for systematic quality measurement
Support ground-truth validation with placeholders in criteria

Experiments

Run batch evaluations combining templates, collections, and LLM configs
Track experiment progress and completion status
Analyze success rates and failure patterns
Compare results across different configurations
Get detailed prompt/response/rating information

Response Annotation

Add notes and categories to responses for iteration tracking
Review annotated responses across experiments

LLM Configuration

Manage multi-provider LLM settings
Configure model parameters, temperature, and API credentials
List available builtin and custom configs

Resources & Guides

Access platform manual (comprehensive MCP usage guide)
Create end-to-end demos for specific use cases

For complete tool documentation, explore tool capabilities directly in your MCP client.

Client Setup¶

Claude Code CLI¶

claude mcp add --transport http elluminate-mcp https://app.elluminate.de/mcp

Authentication Flow

After adding the MCP server, start Claude Code
Navigate to /mcp when prompted
Click the authorization link to open your browser
Sign in to elluminate and authorize access
Return to Claude Code - you're now connected

Verification

Check available MCP servers:

/mcp

You should see elluminate-mcp listed. Try listing your projects:

Can you list my elluminate projects?

Claude Desktop¶

Claude Desktop allows you to add remote MCP servers through the Connectors interface.

Setup Steps¶

Open Settings: Launch the Claude Desktop app and click the Settings icon or navigate to the menu
Go to Connectors: In the sidebar, find and click on Connectors
Add Connector: Scroll down and click the Add custom connector button
Enter Details:
Name: elluminate
URL: https://app.elluminate.de/mcp
Advanced settings: Add your API key from Settings or configure OAuth credentials
Add & Test: Click Add, then start a new chat to use the elluminate integration

Verification¶

Test the connection by asking: "Can you list my elluminate projects?"

ChatGPT App¶

ChatGPT app supports MCP servers through the Connectors interface. This requires a paid subscription (Plus, Team, or Enterprise).

Enable Developer Mode¶

Open ChatGPT and go to your Settings (click your avatar)
Navigate to Apps & Connectors > Advanced settings (or Developer Mode)
Toggle Developer Mode on

Add the Connector¶

Return to the main Settings menu and select Connectors (or Apps & Connectors)
Click the Create button to add a new connector
Configure the connector:
Name: elluminate
Description: "elluminate MCP server for prompt evaluation and experiment tracking"
MCP Server URL: https://app.elluminate.de/mcp
Authentication: Choose OAuth and complete the authorization flow
Trust: Check the box to confirm you trust the provider
Click Create and complete the OAuth authorization

Verification¶

Once connected, use the elluminate server in chats by mentioning it:

@elluminate Can you list my projects?

Codex¶

Codex (OpenAI's development tool) supports MCP servers through configuration in ~/.codex/config.toml.

CLI Configuration¶

codex mcp add elluminate-mcp --url https://app.elluminate.de/mcp

You get forwarded to your browser for OAuth authorization and after granting permission the MCP server is connected to codex.

Manual Configuration¶

Alternatively, edit ~/.codex/config.toml directly:

[mcp_servers.elluminate-mcp]
url = "https://app.elluminate.de/mcp"

You should get forwarded to OAuth. If not authenticate via CLI:

codex mcp login elluminate-mcp

This will open a browser for OAuth authorization.

Verification¶

Restart Codex or reload the configuration
elluminate MCP tools should be available in the tool palette
Test: "Can you list my elluminate projects?"

Gemini CLI¶

Gemini CLI supports MCP servers through configuration in ~/.gemini/settings.json.

Configuration¶

Edit ~/.gemini/settings.json (where ~ is your home directory):

{
  "mcpServers": {
    "elluminate-mcp": {
      "url": "https://app.elluminate.de/mcp"
    }
  }
}

Authentication¶

After editing the configuration file, start Gemini CLI and authenticate:

gemini

Then run the following command to trigger OAuth:

/mcp auth elluminate-mcp

This will open a browser for OAuth authorization.

Verification¶

Restart Gemini CLI or reload the configuration
elluminate MCP tools should be available
Test: "Can you list my elluminate projects?"

Authentication¶

The MCP server supports two authentication methods: OAuth 2.0 for interactive use and API keys for programmatic access.

OAuth Authentication (Recommended)¶

How It Works

Browser-based authorization flow
Tokens validated via userinfo endpoint
Automatic token refresh

When to Use

Interactive sessions with Claude or other AI assistants
Multi-user environments
User-scoped access control

Authorization Flow

MCP client initiates OAuth using the server's auth endpoints
OAuth proxy redirects to elluminate authorization page
User authenticates (or uses existing session)
elluminate redirects back with authorization code
Proxy exchanges code for access token
Client receives bearer token for subsequent requests
Server validates tokens via userinfo endpoint

API Key Authentication¶

How It Works

Direct SDK authentication using API keys
No browser interaction required
Keys scoped to specific projects

When to Use

Programmatic access via custom scripts
Automated testing
CI/CD pipelines

Setup

Generate an API key by navigating to Settings
Set environment variable:
```
export ELLUMINATE_API_KEY="el_..."
```

Security Considerations

Never commit API keys to version control
Use secrets management (1Password, AWS Secrets Manager, etc.)
Rotate keys regularly
Scope keys to specific projects when possible

Environment Variables Reference¶

Configuration options for MCP clients:

Variable	Purpose	Required	Example
`ELLUMINATE_BASE_URL`	elluminate API base URL	Yes	`https://app.elluminate.de`
`ELLUMINATE_API_KEY`	API key for authentication	Yes (if using API key auth)	`el_...`

Common Use Cases¶

Creating and Running Experiments¶

Scenario: Evaluate a customer support chatbot prompt across different scenarios.

I want to evaluate a customer support prompt. Can you help me:
1. Create a new prompt template for handling refund requests
2. Build a test collection with 10 diverse scenarios
3. Set up evaluation criteria for politeness, accuracy, and helpfulness
4. Run an experiment and show me the results

The AI assistant will guide you through each step, creating resources and running the experiment. After completion, ask for detailed analysis:

Show me the failed test cases and explain why they failed

Iterating on Prompts¶

Scenario: Improve prompt based on experiment results.

Based on the experiment results, can you:
1. Clone the prompt template
2. Modify it to address the politeness failures
3. Run a new experiment with the same test cases
4. Compare the results

A/B Testing Configurations¶

Scenario: Compare GPT-4 vs Claude performance.

I want to compare GPT-4 and Claude on my prompt. Can you:
1. List available LLM configs
2. Run two experiments in parallel with different models
3. Show me which model performed better on each criterion

Analyzing Response Patterns¶

Scenario: Deep-dive into specific failures.

Can you:
1. Get the failed examples from experiment X
2. Show me the full prompts and responses for the failed cases
3. Annotate the most problematic responses with "needs-revision"
4. Suggest improvements based on the failure patterns

Troubleshooting¶

Authentication Failed¶

Symptoms: "Authentication failed" or "Unauthorized" errors

Solutions

OAuth: Re-authenticate with browser flow (check /mcp in Claude Code)
API Key: Verify ELLUMINATE_API_KEY is set correctly
Token Expiration: Re-authorize if tokens expired (OAuth only)

Project Not Found¶

Symptoms: "Project not found" when creating resources

Solutions

Call get_project() to verify current project
Use list_projects() to see available projects
Explicitly switch project context after creating/cloning

Connection Refused¶

Symptoms: Cannot connect to MCP server

Solutions

Verify network connectivity to https://app.elluminate.de
Check firewall/proxy settings
Ensure MCP endpoint is accessible: https://app.elluminate.de/mcp