docs
MCP Server
MCP Server Setup

MCP Server Setup

The Zomma Labs MCP (Model Context Protocol) Server allows you to integrate our Knowledge Graph and Agentic OS directly into Claude Desktop and other MCP-compatible clients.

What is MCP?

Model Context Protocol (MCP) is an open standard that enables AI assistants to securely access external data sources and tools. The Zomma Labs MCP server provides Claude and other assistants with access to:

  • Financial knowledge graph queries
  • Real-time market data
  • Agent-based scenario simulation
  • Causal reasoning tools

Installation

Prerequisites

  • Node.js 18 or higher
  • Claude Desktop (or another MCP-compatible client)
  • Zomma Labs API key

Install via NPM

npm install -g @zomma/mcp-server

Install via UV (Python)

uv pip install zomma-mcp-server

Configuration

Claude Desktop

Add the Zomma Labs MCP server to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zomma": {
      "command": "npx",
      "args": ["-y", "@zomma/mcp-server"],
      "env": {
        "ZOMMA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using UV

If you installed via Python/UV:

{
  "mcpServers": {
    "zomma": {
      "command": "uvx",
      "args": ["zomma-mcp-server"],
      "env": {
        "ZOMMA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

Once configured, the following tools are available in Claude:

1. Query Knowledge Graph

query_knowledge_graph(
    entity: str,
    relationship_types: list[str] = None,
    time_range: tuple[str, str] = None
)

Query the financial knowledge graph for facts and relationships.

Example:

Query the knowledge graph for all acquisitions by Apple Inc in 2023

2. Simulate Scenario

simulate_scenario(
    scenario: str,
    portfolio: dict = None,
    time_horizon: str = "3 months"
)

Run agent-based scenario simulation.

Example:

What happens to a tech-heavy portfolio if interest rates rise by 100bps?

3. Analyze Causal Chain

analyze_causal_chain(
    event: str,
    depth: int = 3,
    min_probability: float = 0.3
)

Trace cause-and-effect relationships in financial markets.

Example:

What are the cascading effects of a Strait of Hormuz closure?

4. Get Market Context

get_market_context(
    entity: str,
    context_type: str = "comprehensive"
)

Retrieve comprehensive market context for a company or asset.

Example:

Get current market context for NVIDIA

Usage Examples

Example 1: Research a Company

In Claude Desktop:

Using the Zomma knowledge graph, tell me about Apple's major
acquisitions in the last 5 years and how they relate to their
AI strategy.

Claude will use the query_knowledge_graph tool to fetch structured data about Apple's acquisitions and their relationships.

Example 2: Portfolio Analysis

I have a portfolio with 40% tech stocks (AAPL, MSFT, NVDA),
30% financials, and 30% bonds. Use Zomma to simulate what
happens if the Fed pivots to rate cuts in Q2.

Claude will use simulate_scenario to model the impact on your portfolio.

Example 3: Event Impact Analysis

Using Zomma's causal reasoning, show me the second and third-order
effects of China restricting rare earth exports.

Claude will use analyze_causal_chain to trace the cascading effects.

Configuration Options

Environment Variables

  • ZOMMA_API_KEY (required): Your Zomma Labs API key
  • ZOMMA_API_URL (optional): Custom API endpoint
  • ZOMMA_TIMEOUT (optional): Request timeout in seconds (default: 30)
  • ZOMMA_MAX_RETRIES (optional): Maximum retry attempts (default: 3)

Advanced Configuration

For advanced users, you can configure additional options:

{
  "mcpServers": {
    "zomma": {
      "command": "npx",
      "args": ["-y", "@zomma/mcp-server"],
      "env": {
        "ZOMMA_API_KEY": "your-api-key-here",
        "ZOMMA_TIMEOUT": "60",
        "ZOMMA_MAX_RETRIES": "5",
        "ZOMMA_CACHE_ENABLED": "true",
        "ZOMMA_LOG_LEVEL": "info"
      }
    }
  }
}

Troubleshooting

Server Not Starting

  1. Verify your API key is correct
  2. Check Node.js version: node --version (should be 18+)
  3. Check the Claude Desktop logs:
    • macOS: ~/Library/Logs/Claude/
    • Windows: %APPDATA%\Claude\Logs\

Tools Not Appearing

  1. Restart Claude Desktop after configuration changes
  2. Verify JSON syntax in config file
  3. Check that the MCP server is running:
npx @zomma/mcp-server --test

Authentication Errors

  • Verify your API key is valid
  • Check your account status and rate limits
  • Ensure the API key has the necessary permissions

Rate Limits

MCP server requests count towards your regular API quota:

  • Free Tier: 1,000 requests/day
  • Pro Tier: 100,000 requests/day
  • Enterprise: Custom limits

Security

The MCP server:

  • Never stores your API key (passed via environment variables)
  • Uses HTTPS for all API communications
  • Validates all inputs before sending to the API
  • Runs locally on your machine

Updates

Keep your MCP server updated:

npm update -g @zomma/mcp-server

Or for UV:

uv pip install --upgrade zomma-mcp-server

Next Steps

Support

For MCP server issues:

Agentic OS API