MCP Workspace

This workspace includes two MCP clients and five finance-focused MCP servers that use free/keyless APIs. Both clients talk to OpenAI and can call tools exposed by the servers discovered from ~/.mcp/config.json.

• mcp/mcp-client: simple single-loop client.
• mcp/mcp-agentic: LangGraph-based client with explicit graph/state handling and tool normalization.
• mcp/mcp-deep-agents: LangGraph “deep agent” with planning (TODOs), scratch files, and MCP tool execution.

Prerequisites

• Python 3.11+
• uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh)
• OpenAI API key in mcp/mcp-client/.env (set OPENAI_API_KEY, optionally OPENAI_BASE_URL and OPENAI_MODEL)

One-time setup

From repo root:

# Create a virtual env with uv and activate it
uv venv .venv
source .venv/bin/activate

# Install the classic client dependencies
uv pip install -e mcp/mcp-client

If you are already inside mcp/mcp-client, install with:

uv pip install -e .

Agentic client:

uv pip install -e mcp/mcp-agentic

If you are already inside mcp/mcp-agentic, install with:

uv pip install -e .

Deep agent:

uv pip install -e mcp/mcp-deep-agents

If you are already inside mcp/mcp-deep-agents, install with:

uv pip install -e .

Configure servers

~/.mcp/config.json should point to the servers in this repo, for example:

{
  "mcpServers": {
    "sec-filings": {
      "command": "uv",
      "args": [
        "--directory",
        "~/mcp/mcp-servers/sec-filings",
        "run",
        "sec_filings.py"
      ]
    },
    "gdelt-news": {
      "command": "uv",
      "args": [
        "--directory",
        "~/mcp/mcp-servers/gdelt-news",
        "run",
        "gdelt_news.py"
      ]
    },
    "macro-data": {
      "command": "uv",
      "args": [
        "--directory",
        "~/mcp/mcp-servers/macro-data",
        "run",
        "macro_data.py"
      ]
    },
    "stooq-prices": {
      "command": "uv",
      "args": [
        "--directory",
        "~/mcp/mcp-servers/stooq-prices",
        "run",
        "stooq_prices.py"
      ]
    },
    "fhfa-hpi": {
      "command": "uv",
      "args": [
        "--directory",
        "~/mcp/mcp-servers/fhfa-hpi",
        "run",
        "fhfa_hpi.py"
      ]
    }
  }
}

Included servers and sample validation questions

• sec-filings (SEC EDGAR submissions/facts, keyless):
  • “List recent filings for CIK 0000320193.”
  • “Fetch company facts keys for CIK 0000789019.”
  • “Summarize submissions for CIK 0001652044.”
• gdelt-news (GDELT DOC API, keyless):
  • “Search news about Tesla stock in the last week.”
  • “Company news for NVDA.”
  • “Topic trends for inflation.”
• macro-data (Treasury Fiscal Data, World Bank, ECB, keyless):
  • “Get recent debt outstanding.”
  • “Get recent Treasury yields.”
  • “World Bank indicator FP.CPI.TOTL for USA, 2015:2023.”