Skip to main content

​
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: 
curl http://localhost:8080/healthz  # OpenFGA

​
Your First Request

Let’s send a message to the agent: 
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

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
Ensure OpenFGA is running:
docker compose ps openfga
docker compose logs openfga

# Restart if needed
docker compose restart openfga
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
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!