Skip to main content

​
Harvey API Overview

The H.A.R.V.E.Y. (Holistic Analysis and Regulation Virtual Expert for You) API is a FastAPI service that provides conversational pricing analysis capabilities. It acts as an MCP (Model Context Protocol) client, launching the Pricing MCP server and exposing HTTP endpoints for frontend consumption.

​
Base URL

When running locally: 
http://localhost:8086
In Docker (default configuration): 
http://harvey-api:8086

​
Architecture

Harvey API follows the MCP client-mediated access model:
  • Client Role: Acts as an MCP client, communicating with the Pricing MCP server
  • Transport: Supports both stdio and sse (Server-Sent Events) transports
  • LLM Integration: Uses OpenAI models for natural language orchestration and planning
  • No Server-Side Keys: The MCP server doesn’t require API keys when used via Harvey

​
Available Endpoints

POST /chat

Conversational endpoint for pricing analysis queries

POST /upload

Upload Pricing2Yaml files for analysis

GET /health

Health check endpoint for monitoring

DELETE /pricing/{filename}

Delete uploaded YAML assets

​
Authentication

Currently, the Harvey API does not require authentication for requests. However, it requires:
  • OPENAI_API_KEY environment variable for LLM operations
  • OPENAI_MODEL environment variable (defaults to gpt-5)
These are configured at the service level, not per-request.

​
Configuration

Key environment variables:
​
MCP_SERVER_MODULE
string
default:"pricing_mcp.mcp_server"
Python module path for the Pricing MCP server entrypoint
​
MCP_TRANSPORT
string
default:"stdio"
Transport mechanism: stdio or sse
​
MCP_SERVER_URL
string
URL for the MCP server when using SSE transport (e.g., http://mcp-server:8085/sse)
​
OPENAI_API_KEY
string
required
OpenAI API key for H.A.R.V.E.Y. assistant
​
OPENAI_MODEL
string
default:"gpt-5"
OpenAI model to use for natural language processing
​
LOG_LEVEL
string
default:"INFO"
Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL

​
Local Development

cd harvey_api
mkdir src/harvey_api/static
uv venv
source .venv/bin/activate
uv pip install -e .[dev]
uvicorn harvey_api.app:app --reload --port 8086

​
Docker Deployment

Build and run the Harvey API container: 
docker build -f harvey_api/Dockerfile -t harvey-api .
docker run --env-file mcp_server/.env -p 8086:8086 harvey-api
Or use Docker Compose (from project root): 
docker-compose up harvey-api

​
MCP Compliance

Harvey follows the MCP 2025-06-18 specification:
  • Calls server tools with structured JSON arguments
  • Expects JSON content blocks in responses
  • Reads server resources using resources/read (e.g., resource://pricing/specification)
  • Does not advertise optional client capabilities for roots, sampling, or elicitation
  • Planning and LLM usage happen client-side

​
Error Handling

The API uses standard HTTP status codes:
  • 200 OK - Successful request
  • 201 Created - Resource created (upload)
  • 204 No Content - Successful deletion
  • 400 Bad Request - Invalid request parameters
  • 404 Not Found - Resource not found
  • 502 Bad Gateway - MCP server communication error

​
CORS

CORS is enabled for all origins (*) to support frontend integration. In production, configure this more restrictively.

​
Next Steps

Chat Endpoint

Learn how to submit pricing queries

Upload YAML

Upload Pricing2Yaml files for analysis

Build docs developers (and LLMs) love

Get started for freeTalk to us