Add MCP (Model Context Protocol) Adapter Support #105

Shashikant86 · 2025-10-10T07:03:38Z

Summary

This PR adds a new adapter for optimizing Model Context Protocol (MCP) tool usage with GEPA. The MCP adapter enables optimization of tool descriptions and system prompts for tools exposed via MCP servers, supporting both local (stdio) and remote (SSE/HTTP) MCP servers.

Features by Added Directories/Files

1. MCP Adapter (`src/gepa/adapters/mcp_adapter/`)

Multi-transport support: stdio (local), SSE, and StreamableHTTP (remote)
Two-pass workflow: First pass for tool calling, second pass for final answers
Lazy loading: Graceful handling of missing MCP SDK
Schema-aware prompts: Automatically generates examples with correct parameter names from tool schemas
Flexible optimization: Optimize tool descriptions, system prompts, or both

2. Example Implementations (`src/gepa/examples/mcp_tool_optimization/`)

local_ollama.py: 100% local optimization using Ollama models
cloud_api.py: Cloud-based optimization using OpenAI/Anthropic APIs
remote_server.py: Optimization with remote MCP servers (SSE/HTTP)

3. Simple MCP Server

simple_mcp_server.py: Lightweight filesystem MCP server for examples
Demonstrates basic MCP server implementation
Used for local testing without external dependencies

Technical

Schema-Aware Prompt Generation

The adapter dynamically generates tool-calling examples using actual parameter names from the MCP tool schema:

# From schema:
{"properties": {"path": {"type": "string"}}}

# Generated example:
{"action": "call_tool", "arguments": {"path": "example_value"}}

This ensures models use correct parameter names, preventing common tool-calling failures.

Multi-Transport Architecture

Supports three MCP transport types:

stdio: Local Python/Node.js processes
SSE: Remote servers via Server-Sent Events
StreamableHTTP: HTTP-based remote servers

Two-Pass Evaluation

First pass: Model decides whether to call tool and extracts arguments
Second pass: Model generates final answer using tool response (if tool was called)

This mirrors real-world LLM tool-use patterns.

Example Usage

There are README files included:

src/gepa/adapters/mcp_adapter/README.md: Adapter API, usage patterns, examples
src/gepa/examples/mcp_tool_optimization/README.md: Example walkthroughs

Breaking Changes

None - this is a new feature that doesn't modify existing functionality.

v2 Enhancements

Multi-Tool, result caching, gpt-oss support

Related Kown Issues

MCP Client SDK

MCP SDK Client doesn't work createf issue here. It should not impact as users will have thier own MCP host and client. We created simple stdio client for demo and once MCP fixes issue we can swich over to client from MCP SDK

GPT-OSS Models

Tested locally with gpt-oss-20b and gpt-oss-120b models but they needs separate implemetation for reasoning (thinking) field and keepig it for next version

GEPA with Small Models

Sometime example with current tools call description works well and GEPA decides not to optimize it as they achieve 100% accuracy however for complex examples GEPA proposes smarter tool description depending on the model used for tool calls.

Happy to make any further changes as needeed OR close the Pull Request if not aligned with GEPA's goal

gunta · 2025-10-12T18:22:18Z

Too exited for this PR. 👏

Questions:

How would this work with MCP Elicitations ?
Is it possible to take in account for it?
And what about Sampling ?

Copilot

Pull Request Overview

This PR adds comprehensive support for optimizing Model Context Protocol (MCP) tool usage with GEPA. The MCP adapter enables optimization of tool descriptions and system prompts for tools exposed via MCP servers, supporting both local (stdio) and remote (SSE/HTTP) transport methods.

Key changes:

Multi-transport MCP adapter: Supports local stdio servers, remote SSE servers, and StreamableHTTP servers with authentication
Complete example suite: Three working examples demonstrating local Ollama optimization, cloud API usage, and remote server integration
Comprehensive test coverage: Full test suite with unit tests, integration tests, and mocked dependencies

Reviewed Changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

File	Description
src/gepa/adapters/mcp_adapter/	Core MCP adapter implementation with multi-transport support and schema-aware prompt generation
src/gepa/examples/mcp_tool_optimization/	Three complete examples and a simple MCP server for demonstrations
tests/test_mcp_adapter/	Comprehensive test suite with fixtures, unit tests, and integration tests
README.md	Updated main README to include MCP adapter in supported adapters list

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-12T19:00:46Z

src/gepa/adapters/mcp_adapter/simple_stdio_client.py

+        result = await self.send_request(
+            "initialize",
+            {
+                "protocolVersion": "2054-10-00",


The protocol version '2054-10-00' appears to be a typo and doesn't match MCP's actual protocol version format. This should likely be '2024-11-05' or another valid MCP protocol version.

Suggested change

"protocolVersion": "2054-10-00",

"protocolVersion": "2024-11-05",

Copilot · 2025-10-12T19:00:46Z

tests/test_mcp_adapter/test_mcp_adapter.py

+    """Test that MCP types can be imported."""
+    from gepa.adapters.mcp_adapter import MCPOutput, MCPTrajectory
+
+    assert MCPDataInst is not None


This assertion checks the wrong variable. It should check MCPOutput since MCPDataInst is imported from a different module on line 15, but the import on lines 471 is for MCPOutput and MCPTrajectory.

Suggested change

assert MCPDataInst is not None

LakshyAAAgrawal · 2025-10-13T06:02:42Z

src/gepa/adapters/mcp_adapter/README.md

+        "tool_arguments": {"path": "config.json"},
+        "final_answer": "The config file contains...",
+    },
+    "Feedback": "The tool was not called. Consider whether calling the tool would help..."


Isn't the feedback inconsistent? Is this an example of actually running the make_reflective_dataset function?

Good Catchm @LakshyAAAgrawal This is clearly misleading and came from my experimentations and copy paste ..As Output shows tools called as true but feedback was opposite .. I will make the feedback as tool called run some experiments and come back to you on this ..this needs to be fixed

I have updated the Feedback to use the tools called and update the readme accordingly.

LakshyAAAgrawal · 2025-10-13T06:10:48Z

src/gepa/adapters/mcp_adapter/mcp_types.py

+        additional_context: Optional additional context for the task
+    """
+
+    user_query: str


Doesn't this assume that there is only one tool in the MCP? Shouldn't we be showcasing/optimizing for the scenario where there are many tools available, the model must select the right tool to call, call the tool correctly, and return the response?

Perhaps another level of generalization could be to enable N (parameter) number of steps where the model makes tool calls before calling finish(answer).

Thanks @LakshyAAAgrawal Thats correct and I included multiple tool support for the next version as thing will be overwhelming if I implement this now. I just want to keep it simple one tool call followed by finish and prove the point that idea works. However, MCP adapter is implemented to handle tools as dictionary so adding multiple tools won't be that difficult. Simply we need to include the set of tools in the prompt and configure number of steps and handle it in the finish. However, do we want in this as part of this PR then I am happy to implement if you are ok with it . I just don't want to slap everything in the one PR

Let me know how can I proceed? We can still use one tool for now add support for multiple when needed or we can build fully featured adapter with multi tool right now .. Happy to proceed either way

@LakshyAAAgrawal Most MCP Tools comes with multi tools so there is no point keeping this to next version so I updated adapter to suport multi tools. I have tested locally with updated local_ollama.py examples worked well with smaller models. Please review the PR again..

Shashikant86 added 2 commits October 9, 2025 10:51

Add Basic implementation of the MCP Adapter

73ec377

Implement MCP Stdio Client

50ea13f

LakshyAAAgrawal requested a review from Copilot October 12, 2025 19:00

Copilot AI reviewed Oct 12, 2025

View reviewed changes

LakshyAAAgrawal reviewed Oct 13, 2025

View reviewed changes

Shashikant86 added 4 commits October 13, 2025 18:51

Fix README typo and adopt copilot feedback

c1398c2

Add Multi Tool Suport

85ff23c

Add Multi Tool Suport for MCP

5aefc72

Update Ollama example and fix CI ruff issues

9bc10b2

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add MCP (Model Context Protocol) Adapter Support #105

Add MCP (Model Context Protocol) Adapter Support #105

Uh oh!

Shashikant86 commented Oct 10, 2025 •

edited

Loading

Uh oh!

gunta commented Oct 12, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 12, 2025

Uh oh!

Copilot AI Oct 12, 2025

Uh oh!

LakshyAAAgrawal Oct 13, 2025

Uh oh!

Shashikant86 Oct 13, 2025

Uh oh!

Shashikant86 Oct 13, 2025

Uh oh!

LakshyAAAgrawal Oct 13, 2025

Uh oh!

Shashikant86 Oct 13, 2025

Uh oh!

Shashikant86 Oct 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	"protocolVersion": "2054-10-00",
	"protocolVersion": "2024-11-05",

Add MCP (Model Context Protocol) Adapter Support #105

Are you sure you want to change the base?

Add MCP (Model Context Protocol) Adapter Support #105

Uh oh!

Conversation

Shashikant86 commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Features by Added Directories/Files

1. MCP Adapter (src/gepa/adapters/mcp_adapter/)

2. Example Implementations (src/gepa/examples/mcp_tool_optimization/)

3. Simple MCP Server

Technical

Schema-Aware Prompt Generation

Multi-Transport Architecture

Two-Pass Evaluation

Example Usage

Breaking Changes

v2 Enhancements

Related Kown Issues

MCP Client SDK

GPT-OSS Models

GEPA with Small Models

Uh oh!

gunta commented Oct 12, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 12, 2025

Choose a reason for hiding this comment

Uh oh!

LakshyAAAgrawal Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

Shashikant86 Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

Shashikant86 Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

LakshyAAAgrawal Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

Shashikant86 Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

Shashikant86 Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Shashikant86 commented Oct 10, 2025 •

edited

Loading

1. MCP Adapter (`src/gepa/adapters/mcp_adapter/`)

2. Example Implementations (`src/gepa/examples/mcp_tool_optimization/`)