Quick Start

Get MCP Server with LangGraph running in 5 minutes

Prerequisites

Before you begin, ensure you have:

• Python 3.10+ (3.11+ recommended)
• Docker & Docker Compose (for infrastructure)
• Git (for cloning the repository)
• An LLM API key (Google Gemini recommended for free tier)

We recommend Google Gemini for getting started - it’s free and has generous limits!

Installation

1. Clone the Repository

   git clone https://github.com/vishnu2kmohan/mcp-server-langgraph.git
   cd mcp_server_langgraph
   
2. Install uv

   uv is a fast Python package manager (10-100x faster than pip):

   # macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Windows (PowerShell)
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   
   # Verify installation
   uv --version
   

   Already have uv? Run uv self update to get the latest version.

3. Install Dependencies

   # uv automatically creates .venv and installs all dependencies
   uv sync
   

   Or use the Makefile:

   make install
   

   No manual venv creation needed! uv sync automatically:

   • Creates .venv if it doesn’t exist
   • Installs all dependencies from pyproject.toml
   • Uses uv.lock for reproducible builds
4. Start Infrastructure

   This starts OpenFGA, Jaeger, Prometheus, and Grafana:

   docker compose up -d
   

   Verify services are running:

   docker compose ps
   
5. Setup OpenFGA

   Initialize the authorization system:

   python scripts/setup/setup_openfga.py
   

   Save the output OPENFGA_STORE_ID and OPENFGA_MODEL_ID - you’ll need them next.

6. Configure Environment

   cp .env.example .env
   

   Edit .env with your values:

   # Get free API key from https://aistudio.google.com/apikey
   GOOGLE_API_KEY=your-api-key-here
   
   # From previous step
   OPENFGA_STORE_ID=01HXXXXXXXXXXXXXXXXXX
   OPENFGA_MODEL_ID=01HYYYYYYYYYYYYYYYY
   
   # JWT secret (change in production!)
   JWT_SECRET_KEY=your-secret-key-change-in-production
   
7. Test the Installation

   Run the example client:

   python examples/client_stdio.py
   

   You should see the agent responding to queries! 🎉

Verify Installation

Check that all services are accessible:

Health Check

curl http://localhost:8080/healthz  # OpenFGA

Your First Request

Let’s send a message to the agent:

Python

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test_agent():
    """Test the MCP agent with a simple query"""
    # Configure server
    server_params = StdioServerParameters(
        command="python",
        args=["-m", "mcp_server_langgraph.mcp.server_stdio"]
    )

    # Connect to agent
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize
            await session.initialize()

            # Send a message using the chat tool
            response = await session.call_tool(
                "chat",
                arguments={"message": "Hello! What can you help me with?"}
            )
            print(response)

## Run the test
asyncio.run(test_agent())
```bash
```bash cURL
## First, get a JWT token (in production, use proper auth)
TOKEN=$(python -c "from mcp_server_langgraph.auth.middleware import AuthMiddleware; from mcp_server_langgraph.core.config import settings; auth = AuthMiddleware(secret_key=settings.jwt_secret_key); print(auth.create_token('alice'))")

## Send a message
curl -X POST http://localhost:8000/message \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello! What can you help me with?"}'

Understanding the Response

The agent returns a structured response:

{
  "content": "I can help you with...",
  "role": "assistant",
  "model": "gemini-2.5-flash-002",
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  },
  "trace_id": "abc123...",
  "authorized": true
}

content · string

The agent’s response text

role · string

Always “assistant” for agent responses

model · string

The LLM model used (supports fallback)

usage · object

Token usage statistics for cost tracking

trace_id · string

OpenTelemetry trace ID for debugging

Next Steps

Configure Authentication

Set up JWT and user management

Add Authorization

Configure fine-grained permissions with OpenFGA

Switch LLM Providers

Use Anthropic, OpenAI, or local models

Deploy to Production

Kubernetes, Helm, and production setup

Troubleshooting

Port already in use

If port 8080 or 8000 is already in use:

# Check what's using the port
lsof -i :8080  # macOS/Linux
netstat -ano | findstr :8080  # Windows

# Stop Docker services
docker compose down

# Restart
docker compose up -d

OpenFGA connection refused

Ensure OpenFGA is running:

docker compose ps openfga
docker compose logs openfga

# Restart if needed
docker compose restart openfga

API key invalid

Verify your API key:

# Check .env file
cat .env | grep API_KEY

# Test directly
curl https://generativelanguage.googleapis.com/v1/models?key=YOUR_KEY

Get a new key from Google AI Studio

Module not found

Ensure dependencies are installed:

# Reinstall dependencies (uv recreates .venv if needed)
uv sync

# Verify Python is using .venv
uv run python -c "import sys; print(sys.prefix)"

# Or activate .venv manually if you prefer bare commands
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate      # Windows

Use uv run <command> to run commands without manual activation.

Need more help? Check the Development Setup guide or ask in GitHub Discussions.

What’s Next?

Now that you have the agent running:

1. Explore the code - Check out agent.py to see how the LangGraph agent works
2. Try different models - Follow the Multi-LLM Setup guide
3. Configure security - Set up proper authentication
4. Deploy it - Follow the deployment guides

Pro Tip: Star the GitHub repository to stay updated with new features!