> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-server-langgraph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)

<Tip>
  We recommend [Google Gemini](https://aistudio.google.com/apikey) for getting started - it's free and has generous limits!
</Tip>

### Installation

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/vishnu2kmohan/mcp-server-langgraph.git
    cd mcp_server_langgraph
    ```
  </Step>

  <Step title="Install uv">
    uv is a fast Python package manager (10-100x faster than pip):

    ```bash theme={null}
    # 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
    ```

    <Tip>
      Already have uv? Run `uv self update` to get the latest version.
    </Tip>
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    # uv automatically creates .venv and installs all dependencies
    uv sync
    ```

    Or use the Makefile:

    ```bash theme={null}
    make install
    ```

    <Note>
      **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
    </Note>
  </Step>

  <Step title="Start Infrastructure">
    This starts OpenFGA, Jaeger, Prometheus, and Grafana:

    ```bash theme={null}
    docker compose up -d
    ```

    Verify services are running:

    ```bash theme={null}
    docker compose ps
    ```
  </Step>

  <Step title="Setup OpenFGA">
    Initialize the authorization system:

    ```bash theme={null}
    python scripts/setup/setup_openfga.py
    ```

    Save the output `OPENFGA_STORE_ID` and `OPENFGA_MODEL_ID` - you'll need them next.
  </Step>

  <Step title="Configure Environment">
    ```bash theme={null}
    cp .env.example .env
    ```

    Edit `.env` with your values:

    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Test the Installation">
    Run the example client:

    ```bash theme={null}
    python examples/client_stdio.py
    ```

    You should see the agent responding to queries! 🎉
  </Step>
</Steps>

### Verify Installation

Check that all services are accessible:

<CodeGroup>
  ```bash Health Check theme={null}
  curl http://localhost:8080/healthz  # OpenFGA
  ```

  ```bash Jaeger UI theme={null}
  open http://localhost:16686
  ```

  ```bash Prometheus theme={null}
  open http://localhost:9090
  ```

  ```bash Grafana theme={null}
  open http://localhost:3001  # admin/admin
  ```
</CodeGroup>

### Your First Request

Let's send a message to the agent:

<CodeGroup>
  ````python Python theme={null}
  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?"}'
  ````

  ```javascript JavaScript theme={null}
  const axios = require('axios');

  // Get token (implement proper auth in production)
  const token = 'your-jwt-token';

  // Send message
  const response = await axios.post('http://localhost:8000/message', {
    query: 'Hello! What can you help me with?'
  }, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });

  console.log(response.data);
  ```
</CodeGroup>

### Understanding the Response

The agent returns a structured response:

```json theme={null}
{
  "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
}
```

<ResponseField name="content" type="string">
  The agent's response text
</ResponseField>

<ResponseField name="role" type="string">
  Always "assistant" for agent responses
</ResponseField>

<ResponseField name="model" type="string">
  The LLM model used (supports fallback)
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics for cost tracking
</ResponseField>

<ResponseField name="trace_id" type="string">
  OpenTelemetry trace ID for debugging
</ResponseField>

### Next Steps

<CardGroup cols={2}>
  <Card title="Configure Authentication" icon="key" href="/getting-started/authentication">
    Set up JWT and user management
  </Card>

  <Card title="Add Authorization" icon="shield" href="/getting-started/authorization">
    Configure fine-grained permissions with OpenFGA
  </Card>

  <Card title="Switch LLM Providers" icon="shuffle" href="/guides/multi-llm-setup">
    Use Anthropic, OpenAI, or local models
  </Card>

  <Card title="Deploy to Production" icon="cloud" href="/deployment/overview">
    Kubernetes, Helm, and production setup
  </Card>
</CardGroup>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Port already in use">
    If port 8080 or 8000 is already in use:

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="OpenFGA connection refused">
    Ensure OpenFGA is running:

    ```bash theme={null}
    docker compose ps openfga
    docker compose logs openfga

    # Restart if needed
    docker compose restart openfga
    ```
  </Accordion>

  <Accordion title="API key invalid">
    Verify your API key:

    ```bash theme={null}
    # 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](https://aistudio.google.com/apikey)
  </Accordion>

  <Accordion title="Module not found">
    Ensure dependencies are installed:

    ```bash theme={null}
    # 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
    ```

    <Tip>
      Use `uv run <command>` to run commands without manual activation.
    </Tip>
  </Accordion>
</AccordionGroup>

<Note>
  **Need more help?** Check the [Development Setup](/advanced/development-setup) guide or ask in [GitHub Discussions](https://github.com/vishnu2kmohan/mcp-server-langgraph/discussions).
</Note>

### 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](/guides/multi-llm-setup) guide
3. **Configure security** - Set up proper [authentication](/getting-started/authentication)
4. **Deploy it** - Follow the [deployment guides](/deployment/overview)

<Info>
  **Pro Tip:** Star the [GitHub repository](https://github.com/vishnu2kmohan/mcp-server-langgraph) to stay updated with new features!
</Info>