IDE Setup Guide - MCP Server with LangGraph

This document provides setup instructions for various IDEs and AI coding assistants when working on the MCP Server with LangGraph project.

General Notes

IDE-Specific Configuration Files: As of v2.0.0, IDE-specific configuration directories (.ai/, .openai/, .cursor/, .claude/, .vscode/) are gitignored to prevent merge conflicts and keep the repository clean. You’ll need to create these directories locally based on your preferences.

Visual Studio Code

Recommended Extensions

Create .vscode/extensions.json:

{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "ms-python.black-formatter",
    "ms-python.isort",
    "charliermarsh.ruff",
    "ms-toolsai.jupyter",
    "redhat.vscode.yaml",
    "tamasfe.even-better-toml",
    "GitHub.copilot",
    "GitHub.copilot-chat"
  ]
}

Python Settings

Create .vscode/settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.analysis.typeCheckingMode": "basic",
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.linting.mypyEnabled": true,
  "python.formatting.provider": "black",
  "python.formatting.blackArgs": ["--line-length=127"],
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.rulers": [127]
  },
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true,
    ".pytest_cache": true,
    ".mypy_cache": true,
    "htmlcov": true
  }
}

Debug Configurations

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src"
      }
    },
    {
      "name": "MCP Server (stdio)",
      "type": "python",
      "request": "launch",
      "module": "mcp_server_langgraph.mcp.server_stdio",
      "console": "integratedTerminal",
      "envFile": "${workspaceFolder}/.env"
    },
    {
      "name": "MCP Server (StreamableHTTP)",
      "type": "python",
      "request": "launch",
      "module": "mcp_server_langgraph.mcp.server_streamable",
      "console": "integratedTerminal",
      "envFile": "${workspaceFolder}/.env"
    },
    {
      "name": "Pytest: Current File",
      "type": "python",
      "request": "launch",
      "module": "pytest",
      "args": ["${file}", "-v"],
      "console": "integratedTerminal"
    }
  ]
}

Tasks

Create .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run Tests (Unit)",
      "type": "shell",
      "command": "pytest",
      "args": ["-m", "unit", "-v"],
      "group": "test",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    },
    {
      "label": "Run Tests (All)",
      "type": "shell",
      "command": "make",
      "args": ["test"],
      "group": {
        "kind": "test",
        "isDefault": true
      }
    },
    {
      "label": "Format Code",
      "type": "shell",
      "command": "make",
      "args": ["format"]
    },
    {
      "label": "Lint",
      "type": "shell",
      "command": "make",
      "args": ["lint"]
    }
  ]
}

Claude Code / Claude Desktop

Configuration

Create .claude/settings.local.json:

{
  "output_style": "concise",
  "project_context": {
    "language": "python",
    "framework": "langgraph",
    "testing": "pytest"
  }
}

Guidance Files

The project includes comprehensive AI assistant guidance:

.github/CLAUDE.md - Complete guide for Claude Code
.github/AGENTS.md - Extended guide with more examples

These files are version-controlled and provide:

Project architecture overview
Development patterns
Common commands
Testing strategy
Security requirements

Cursor

MCP Configuration

Create .cursor/mcp.json (Cursor supports ${workspaceFolder} variables):

{
  "mcpServers": {
    "langgraph-agent": {
      "command": "python",
      "args": [
        "-m",
        "mcp_server_langgraph.mcp.server_stdio"
      ],
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src"
      },
      "envFile": "${workspaceFolder}/.env"
    },
    "langgraph-agent-streamable": {
      "command": "python",
      "args": [
        "-m",
        "mcp_server_langgraph.mcp.server_streamable"
      ],
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src",
        "HOST": "0.0.0.0",
        "PORT": "8000"
      },
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Note: The .cursor/ directory is gitignored, so you need to create this configuration locally.

Settings

Cursor will use the VS Code settings above, but you can override: Create .cursor/settings.json:

{
  "cursor.chat.model": "claude-sonnet-4-5-20250929",
  "cursor.tab.model": "claude-sonnet-4-5-20250929"
}

GitHub Copilot Workspace

Instructions

Create .github/copilot-instructions.md:

## GitHub Copilot Instructions

This project uses:
- Python 3.10-3.12
- LangGraph for agent orchestration
- pytest with multiple test markers (unit, integration, property, contract)
- Black formatter (line-length=127)
- Type hints required for all public APIs

When generating code:
1. Follow Google-style docstrings
2. Use type hints
3. Add appropriate pytest markers
4. Check authorization before privileged operations
5. Add observability (tracing, metrics, logging)

See `.github/AGENTS.md` for complete guidance.

AI Coding Assistants (.ai/)

General AI Tools Configuration

Create .../../README.md:

## AI Coding Assistant Configuration

This directory contains configuration for AI coding assistants.

### Setup

See the appropriate section in `docs/development/ide-setup.md`:
- Claude Code/Desktop
- GitHub Copilot
- Cursor
- Codeium
- Tabnine

### Guidance Files

The project provides comprehensive AI assistant guidance in version control:
- `.github/CLAUDE.md` - For Claude-based assistants
- `.github/AGENTS.md` - For all AI assistants (extended)
- `.github/copilot-instructions.md` - For GitHub Copilot

These files contain:
- Architecture overview
- Development patterns
- Code standards
- Testing strategy
- Common issues & solutions

Create .ai/prompts.md with your custom prompts for reuse.

OpenAI Codex

Configuration

Create .openai/code-completion-config.json:

{
  "model": "gpt-5.1-pro",
  "temperature": 0.2,
  "max_tokens": 2048,
  "context": {
    "project_type": "python-langgraph",
    "framework": "langgraph",
    "testing": "pytest",
    "style": "black",
    "line_length": 127
  }
}

Create .openai/codex-instructions.md referencing .github/AGENTS.md for detailed project guidance.

MCP Server Configuration

All MCP-compatible IDEs can use the MCP server configuration.

MCP Manifest

The project includes .mcp/manifest.json and .mcp/registry.json for MCP registry publication. These are version-controlled.

Client Configuration

Quick Setup

The project includes .mcp.json.example as a template. To set it up:

## Copy the example file
cp .mcp.json.example .mcp.json

## Edit with your absolute paths
## Replace /absolute/path/to/mcp-server-langgraph with your actual project path
nano .mcp.json  # or use your preferred editor

Note: .mcp.json is gitignored (user-specific configuration). Each developer needs to create their own based on where they cloned the repository.

Manual Configuration

For Claude Desktop or other MCP clients, add to your client config:

{
  "mcpServers": {
    "langgraph-agent": {
      "command": "python",
      "args": [
        "-m",
        "mcp_server_langgraph.mcp.server_stdio"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/project/src"
      },
      "envFile": "/absolute/path/to/project/.env"
    },
    "langgraph-agent-streamable": {
      "command": "python",
      "args": [
        "-m",
        "mcp_server_langgraph.mcp.server_streamable"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/project/src",
        "HOST": "0.0.0.0",
        "PORT": "8000"
      },
      "envFile": "/absolute/path/to/project/.env"
    }
  }
}

Important: Replace /absolute/path/to/project with your actual project directory. For example:

Linux/macOS: /home/username/projects/mcp-server-langgraph
Windows: C:/Users/username/projects/mcp-server-langgraph

PyCharm / IntelliJ IDEA

Project Interpreter

File → Settings → Project → Python Interpreter
Click gear → Add → Existing Environment
Select .venv/bin/python

Code Style

File → Settings → Editor → Code Style → Python
Set “Hard wrap at” to 127
Import pyproject.toml settings if supported (PyCharm 2023.3+)

Run Configurations

Create run configurations for:

pytest (unit): Target = tests/, Additional args = -m unit -v
pytest (all): Target = tests/, Additional args = -v
MCP Server: Script path = src/mcp_server_langgraph/mcp/server_stdio.py

External Tools

Add Make commands as external tools:

File → Settings → Tools → External Tools
Add: make test, make lint, make format, etc.

General Best Practices

Virtual Environment

Preferred approach: Use uv run to run commands without manual activation:

## Preferred: No activation needed
uv run pytest -m unit -v
uv run python -m mcp_server_langgraph.mcp.server_stdio
uv run python examples/demo.py

Alternative: Activate the virtual environment manually (if running multiple commands):

source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate      # Windows

## Now can use bare commands
pytest -m unit -v
python -m mcp_server_langgraph.mcp.server_stdio

IDEs can use .venv/bin/python directly without requiring manual activation. Set your IDE’s Python interpreter to .venv/bin/python and it will use the virtual environment automatically.

Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env
## Edit .env with your API keys

Never commit .env - it’s gitignored for security.

Pre-commit Hooks

Install pre-commit hooks:

pre-commit install

This ensures:

Code is formatted (black, isort)
Linting passes (flake8)
Security scan (bandit)
Tests run before commit (optional)

Troubleshooting

Import Errors

If imports fail:

Ensure virtual environment is activated

Check PYTHONPATH includes src/:

export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"

Reinstall dependencies:
uv sync

IDE Not Finding Modules

VS Code: Set python.defaultInterpreterPath to .venv/bin/python
PyCharm: Configure project interpreter to .venv/bin/python
All IDEs: Mark src/ as sources root

Tests Not Running

Ensure pytest is installed: uv sync
Check test markers are registered: pytest --markers
Verify conftest.py is found: pytest --collect-only

Contributing

When adding IDE configurations:

Do NOT commit user-specific settings to .vscode/, .cursor/, etc.
Do commit recommendations in this file
Do add examples for new IDE setup
Do update this guide if project structure changes

See ../../.github/CONTRIBUTING.md for contribution guidelines.

References

Project Documentation: do../../README.md
AI Assistant Guidance: .github/CLAUDE.md, .github/AGENTS.md
Development Guide: docs/development/development.md
Testing Guide: docs/development/testing.md

Last Updated: 2025-10-12

​General Notes

​Visual Studio Code

​Recommended Extensions

​Python Settings

​Debug Configurations

​Tasks

​Claude Code / Claude Desktop

​Configuration

​Guidance Files

​Cursor

​MCP Configuration

​Settings

​GitHub Copilot Workspace

​Instructions

​AI Coding Assistants (.ai/)

​General AI Tools Configuration

​OpenAI Codex

​Configuration

​MCP Server Configuration

​MCP Manifest

​Client Configuration

Quick Setup

Manual Configuration

​PyCharm / IntelliJ IDEA

​Project Interpreter

​Code Style

​Run Configurations

​External Tools

​General Best Practices

​Virtual Environment

​Environment Variables

​Pre-commit Hooks

​Troubleshooting

​Import Errors

​IDE Not Finding Modules

​Tests Not Running

​Contributing

​References

General Notes

Visual Studio Code

Recommended Extensions

Python Settings

Debug Configurations

Tasks

Claude Code / Claude Desktop

Configuration

Guidance Files

Cursor

MCP Configuration

Settings

GitHub Copilot Workspace

Instructions

AI Coding Assistants (.ai/)

General AI Tools Configuration

OpenAI Codex

Configuration

MCP Server Configuration

MCP Manifest

Client Configuration

PyCharm / IntelliJ IDEA

Project Interpreter

Code Style

Run Configurations

External Tools

General Best Practices

Virtual Environment

Environment Variables

Pre-commit Hooks

Troubleshooting

Import Errors

IDE Not Finding Modules

Tests Not Running

Contributing

References