MCP Integration Guide

MCP Integration Guide

Model Context Protocol (MCP) enables the agent to execute external tools. This is optional - the agent works without it.

What is MCP?

MCP provides tool execution via JSON-RPC 2.0:

• External tools: Search products, get purchase history, fetch web pages
• Server-side execution: Tools run on MCP server, not locally
• Authentication: Requires auth token from AWS Secrets Manager

When enabled, the agent can call 6 tools for shopping assistance.

Setup Checklist

Prerequisites

• AWS CLI configured with SSO access
• Access to rover-mcp/auth-tokens in AWS Secrets Manager
• MCP server URL (stage or prod)

Configuration Steps

1. Get auth token from AWS:

# Login to AWS SSO
aws sso login --profile stage-services-admin

# Retrieve token
aws secretsmanager get-secret-value \
  --secret-id rover-mcp/auth-tokens \
  --profile stage-services-admin \
  --query SecretString \
  --output text

2. Add token to .env:

# Copy example file if needed
cp .env.example .env

# Edit .env and add:
ROVER_MCP_AUTHORIZATION=your-token-from-aws

3. Verify MCP config in settings.yaml:

rover_mcp:
  server_url: https://stage-partners-gateway.fetchrewards.com/rover-mcp
  timeout: 90.0

4. Test connection:

# Direct server test
curl -H "Authorization: Bearer $ROVER_MCP_AUTHORIZATION" \
  https://stage-partners-gateway.fetchrewards.com/rover-mcp/health

Expected response: {"status": "ok"}

Available Tools

The agent has access to 6 MCP tools:

1. search_products

Search for products by description.

Input:

{
    "descriptions": ["Mountain Dew", "eggs", "organic milk"]
}

Use case: Find specific products or categories.

2. search_offers

Search for available offers.

Input:

{
    "query": "summer treats",
    "user_id": "user123",
    "limit": 200
}

Use case: Find relevant offers for a user.

3. search_nearby_offers

Search for offers near a location.

Input:

{
    "user_id": "user123",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "query": "coffee drinks"
}

Use case: Find offers at nearby stores.

4. get_user_purchase_history

Get user’s past purchases with optional filtering.

Input:

{
    "user_id": "user123",
    "start_time": "2024-01-01T00:00:00Z",  # optional, RFC3339, defaults to 90 days ago
    "end_time": "2024-12-31T23:59:59Z",    # optional, RFC3339, defaults to now
    "category": "snacks",                   # optional, natural language filter
    "brand": "coca cola"                    # optional, natural language filter
}

Use case: Understand user preferences and shopping patterns. Supports semantic search for category/brand filtering.

5. fetch_webpage

Fetch and parse a webpage.

Input:

{
    "url": "https://example.com",
    "depth": 0  # 0-2, prevents crawling
}

Use case: Extract content from web pages.

6. llm_feedback

Submit feedback about tools.

Input:

{
    "message": "User wanted to search by brand"
}

Use case: Report feature requests or missing capabilities.

How to Enable

In Agent Code

Pass MCP config when creating the agent:

from consumer_agent.agent import Agent
from consumer_agent.factory import create_chat_model
from consumer_agent.utils.tools import build_mcp_tools
from consumer_agent.config import settings

# Build tools if MCP is configured
tools = []
if settings.rover_mcp.server_url and settings.rover_mcp.authorization:
    tools = build_mcp_tools(
        server_url=settings.rover_mcp.server_url,
        auth_token=settings.rover_mcp.authorization,
        timeout=settings.rover_mcp.timeout
    )

# Create agent with tools
model = create_chat_model()
agent = Agent(model, tools=tools)

In FastAPI Service

MCP is automatically enabled if ROVER_MCP_AUTHORIZATION is set:

# From src/consumer_agent/api/main.py
# Tools are created via factory.create_agent_from_config()
# which checks settings.rover_mcp configuration
agent = create_agent_from_config(agent_id="conversational")

Tool Architecture

Custom Tool Wrappers

Each tool is a LangChain BaseTool wrapper (src/consumer_agent/utils/tools.py) that provides:

• Provider-agnostic: Works with any LLM, not just OpenAI
• Type safety: Pydantic schemas validate inputs
• Error handling: Catches and logs errors gracefully
• Async: Non-blocking tool execution

MCP Client

JSON-RPC 2.0 client for server communication (src/consumer_agent/utils/mcp_client.py). Handles tool calls and tool listing.

Features:

• Auto-formats auth header (adds “Bearer” prefix)
• Constructs MCP endpoint URL (adds “/mcp” suffix)
• Handles JSON-RPC errors
• Logs all requests/responses

Usage Examples

Agent with MCP Tools

from consumer_agent.agent import Agent
from consumer_agent.factory import create_chat_model
from consumer_agent.utils.tools import build_mcp_tools
from consumer_agent.config import settings

# Setup
tools = build_mcp_tools(
    settings.rover_mcp.server_url,
    settings.rover_mcp.authorization,
    settings.rover_mcp.timeout
)

model = create_chat_model()
agent = Agent(model, tools=tools)

# Use agent
messages = [{"role": "user", "content": "Find offers for coffee"}]
system_prompt = "You are a shopping assistant."

async for event in agent.stream(messages, system_prompt):
    if isinstance(event, ToolCallStartEvent):
        print(f"Calling: {event.tool_name}")
    elif isinstance(event, TextEvent):
        print(event.content)

Check Available Tools

from consumer_agent.utils.mcp_client import MCPClient
from consumer_agent.config import settings

client = MCPClient(
    settings.rover_mcp.server_url,
    settings.rover_mcp.authorization,
    settings.rover_mcp.timeout
)

# List tools from server
tools = await client.list_tools()
for tool in tools:
    print(f"- {tool['name']}: {tool['description']}")

Call Tool Directly

from consumer_agent.utils.mcp_client import MCPClient

client = MCPClient(server_url, auth_token, timeout=90.0)

# Search for products
result = await client.call_tool(
    "search_products",
    {"descriptions": ["coffee", "milk"]}
)
print(result)

Troubleshooting

Error: ROVER_MCP_AUTHORIZATION environment variable not found

MCP is optional. This is not an error if you don’t need tools.

To enable MCP:

1. Get auth token from AWS Secrets Manager (see setup checklist)
2. Add to .env: ROVER_MCP_AUTHORIZATION=your-token

Error: MCPError: Unauthorized (401)

Auth token is invalid or expired.

Fix:

1. Retrieve fresh token from AWS Secrets Manager
2. Update .env with new token
3. Restart application

Error: httpx.TimeoutException

MCP server did not respond within timeout.

Fix:

# Increase timeout in settings.yaml
rover_mcp:
  timeout: 120.0  # Increase from 90

Tool calls fail with Error executing tool

Check MCP server status:

curl -H "Authorization: Bearer $ROVER_MCP_AUTHORIZATION" \
  https://stage-partners-gateway.fetchrewards.com/rover-mcp/health

If server is down, contact infrastructure team.

Agent doesn’t call tools

Possible causes:

1. Tools not bound: Verify tools passed to agent constructor
2. System prompt: Prompt may discourage tool use
3. Model limitations: Some models prefer not to use tools

Debug:

# Check if tools are loaded
print(f"Agent has {len(agent._tools)} tools")
for tool in agent._tools:
    print(f"  - {tool.name}")

ImportError: No module named 'consumer_agent.utils.tools'

Dependencies not installed or virtual environment not activated.

Fix:

uv sync
source .venv/bin/activate

Disabling MCP

To run without MCP:

1. Remove from .env:

# Delete or comment out:
# ROVER_MCP_AUTHORIZATION=...

2. Agent still works:

# Without ROVER_MCP_AUTHORIZATION, no tools are loaded
agent = create_agent_from_config(agent_id="conversational")
# Agent has no tools but operates normally using LLM knowledge

The agent operates normally without tools, using only its knowledge.

References

• Setup Guide - Environment configuration
• Architecture Guide - Tool execution flow
• Development Guide - Testing with MCP