biz-mcp

A custom MCP (Model Context Protocol) server with 7 tools that connect to an LLM/MCP client. It combines:

• 2 external API wrappers - live FX rates (ECB/Frankfurter) and crypto prices (CoinGecko), both free and key-less.

• 2 database operations - a key-value store backed by DynamoDB on AWS (falls back to a local JSON file for development).

• 3 business-logic tools - invoice calculation, shipping estimation, and inventory-status assessment.

It runs on AWS Lambda behind a Lambda Function URL using the modern streamable HTTP MCP transport. The same code runs locally over stdio (for Claude Desktop) or streamable HTTP.

Tools

Related MCP server: Atlas MCP Server

Architecture

MCP client (Claude Desktop, Cursor, mcp inspector)
        │  streamable HTTP (POST JSON-RPC / SSE)
        ▼
Lambda Function URL  ──►  lambda_function.py (protocol adapter)
                                   │
                                   ▼
                            mcp_server.py (FastMCP, 7 tools)
                              ├── apis.py      → frankfurter.app, CoinGecko
                              ├── db.py        → DynamoDB (or local JSON)
                              └── business.py  → invoice, shipping, inventory

Project layout

apis.py             External API wrappers
business.py         Pure business logic
db.py               Key-value store (DynamoDB or local JSON)
mcp_server.py       FastMCP server defining the 7 tools
lambda_function.py  Streamable-HTTP JSON-RPC adapter for Lambda
template.yaml       SAM template (Lambda + Function URL + DynamoDB)
deploy.ps1          One-command deployment for Windows
tests/              pytest suite (unit + lambda handler + stdio E2E)

Local setup

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements-dev.txt

Check the tests

pytest

Run locally

• stdio (default, for Claude Desktop and the inspector):

python mcp_server.py

• streamable HTTP (for browsers / HTTP clients):

python mcp_server.py --transport http
# serves at http://127.0.0.1:8000/mcp

Try it with the MCP Inspector

npx @modelcontextprotocol/inspector python mcp_server.py

Deploy to AWS Lambda

Prerequisites: AWS CLI (aws configure) and SAM CLI.

.\deploy.ps1

The script builds dependencies (build_deps.ps1), packages the template, and creates/updates the stack. sam deploy/sam package creates:

• a Lambda function (biz-mcp) with the Python 3.12 runtime,

• a Lambda Function URL (public, HTTPS, AuthType: NONE) with permissive CORS,

• a DynamoDB table (biz-mcp-store, pk/sk composite key, on-demand capacity) plus the IAM policy so the Lambda can access it,

• Lambda url:Invoke and Function:Invoke permissions (both are required since Oct 2025 for Function URLs with AuthType: NONE).

Notes on the deploy path:

• FunctionUrl.Cors.AllowMethods does not accept OPTIONS (supported enum: GET | PUT | HEAD | POST | PATCH | DELETE | *). Omit it; Lambda handles preflight automatically.

• Deployment uses sam package + aws cloudformation create-stack/update-stack directly rather than a changeset, because the CloudFormation AWS::EarlyValidation::PropertyValidation hook (Nov 2025) can spuriously fail changeset creation. sam build is not run on Windows; dependencies are built into build/mcp.zip by build_deps.ps1 via uv.

Manual equivalents:

.\build_deps.ps1                                                        # build build/mcp.zip
sam package --template-file template.yaml --resolve-s3 --output-template-file packaged.yaml
aws cloudformation create-stack --stack-name biz-mcp --template-body file://packaged.yaml `
    --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND

Point an MCP client at it

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "biz-mcp": {
      "type": "http",
      "url": "https://YOUR_ENDPOINT/"
    }
  }
}

The MCP Inspector also accepts an HTTP server URL directly.

Run the bundled agent (free Groq brain)

agent/agent.py is a ready-made agent that connects to the MCP endpoint and uses a free-tier Groq model to drive the 7 tools with native function calling.

# use the project venv so openai/mcp deps don't clash with other Python installs
& "C:\Users\lenovo\AppData\Local\Programs\Python\Python312\python.exe" -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r agent/requirements.txt
# get a free key once at https://console.groq.com/keys
setx GROQ_API_KEY "gsk_..."

python agent/agent.py --url https://YOUR_ENDPOINT/
# or a one-shot question:
python agent/agent.py --url https://YOUR_ENDPOINT/ `
  --question "Convert 250 USD to EUR, then save it as pk=1201 sk=usd-eur"

The agent lists the MCP tools, then chains tool calls until it can answer (it can save/read records in DynamoDB, check inventory, price orders and shipping, and pull live FX/crypto rates). Check the current free model id with GET /openai/v1/models and pass it via --model if the default is unavailable.

Smoke test without a client

curl -s -X POST https://YOUR_ENDPOINT/ `
  -H "Content-Type: application/json" `
  -H "Accept: application/json, text/event-stream" `
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

tools/list will return the 7 tools:

curl -s -X POST https://YOUR_ENDPOINT/ `
  -H "Content-Type: application/json" `
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

How the transport works

lambda_function.py implements the MCP streamable HTTP protocol directly on Lambda:

• POST with a JSON-RPC body; notifications return 202, requests return 200.

• If the client sends Accept: application/json it receives a single JSON-RPC response.

• If the client sends Accept: text/event-stream it receives the same response wrapped in one SSE message event, so streaming-capable clients work without requiring API Gateway's response-streaming features.

• OPTIONS preflight plus plain API-Gateway v1/v2 proxy and Lambda-Function-URL events are handled by the same normalizer.

No long-lived connections are needed, which is exactly what makes this Lambda-friendly.

Security notes (read before going public)

• The Function URL is AuthType: NONE, meaning anyone with the URL can invoke the Lambda.

• Each public call invokes billing and lets anyone read/write the DynamoDB table.

• For production: set AuthType: AWS_IAM and use a SigV4-signed MCP client, add request throttling, or front the URL with WAF. The tools also accept arbitrary pk/sk, so add an authorization layer (e.g. per-tenant key prefix) if the data is sensitive.

• CoinGecko and Frankfurter free tiers have rate limits; failures surface as tool errors.

Customization

• Add tools: define a function in mcp_server.py with the @mcp.tool() decorator and a docstring; the JSON schema is generated automatically. Rebuild/sam deploy to publish.

• Note: mcp is pinned to >=1.30,<2 because mcp 2.x hard-depends on pywin32 on Windows, which breaks sam build on Windows hosts. The API used here is identical in v2 (just import MCPServer instead of FastMCP).

• Swap the store: keep db.py's interface (save_item, get_item, list_items) and implement a new backend (e.g. RDS, S3).

• Switch transport: the built-in mcp.run(transport="streamable-http") path runs the same tools as a plain web server if you ever move to EC2 instead.