MCP Server Project Setup

Once you’ve decided to build a custom MCP server (see Custom MCP Server Decision Criteria) and chosen your SDK (see MCP SDK Selection for Data Engineering), the actual project setup takes about 10 minutes. This walkthrough covers the Python path with FastMCP, which is the most common choice for data engineering teams.

1. Initialize the Project

With uv (recommended):

uv init my-data-mcp-server
cd my-data-mcp-server

Or with standard Python:

mkdir my-data-mcp-server
cd my-data-mcp-server
python -m venv .venv
source .venv/bin/activate

uv is the faster path — it handles virtual environment creation, dependency resolution, and lockfiles automatically. If you’re already using uv for other Python projects, this is the natural choice.

2. Add Dependencies

# Core MCP with CLI tools
uv add "mcp[cli]"

# Common data engineering dependencies
uv add httpx          # HTTP client for API calls
uv add pydantic       # Data validation (usually included with mcp)
uv add sqlalchemy     # Database connections
uv add asyncpg        # Async PostgreSQL (if needed)

Start lean. You can always add dependencies later. The only essential dependency is mcp[cli] — everything else depends on what your server connects to.

3. Create the Server File

Create server.py with the FastMCP Server Skeleton as a starting point, then add your tools. For a data engineering server, you’ll typically need to import your data stack’s client libraries — the BigQuery client, Airflow’s REST client, your catalog’s SDK — alongside the MCP SDK.

4. Test with MCP Inspector

npx @modelcontextprotocol/inspector uv run server.py

Open the URL shown in your browser. Verify:

• All tools appear in the list
• Descriptions are clear and accurate
• Input schemas look correct (types, defaults, constraints)
• Tools execute without errors on valid input
• Error handling returns useful messages

The MCP Server Testing and Debugging note covers the full testing workflow, including the stderr logging gotcha that will bite you if you use print() statements.

5. Install to Claude Desktop

The quick install command creates a config entry automatically:

uv run mcp install server.py --name "My Data Server"

Or manually edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "my-data-server": {
      "command": "uv",
      "args": ["run", "/full/path/to/server.py"],
      "env": {
        "DATABASE_URL": "your-connection-string"
      }
    }
  }
}

Use the full absolute path to server.py. Relative paths are unreliable because the host application’s working directory may not be what you expect.

6. Install to Claude Code

For personal use:

claude mcp add my-data-server -- uv run /full/path/to/server.py

For team projects (creates a .mcp.json file that can be committed):

claude mcp add my-data-server -s project -- uv run /full/path/to/server.py

The project-scoped configuration means teammates clone the repo and get the same MCP setup automatically. No manual configuration per developer.

7. Test in the Real Client

claude
> What tools does my-data-server provide?
> [Test each tool with realistic inputs]

This integration test reveals issues that the Inspector doesn’t catch — how the AI interprets your descriptions, whether it passes parameters correctly, and whether response formats are useful in conversation. See MCP Server Testing and Debugging for the full three-stage testing workflow.

Project Structure

A typical MCP server project:

my-data-mcp-server/
├── pyproject.toml      # Dependencies and metadata
├── server.py           # Main server file
├── tools/              # Tool implementations (optional, for large servers)
│   ├── __init__.py
│   ├── catalog.py
│   └── quality.py
├── tests/              # Unit tests for business logic
│   └── test_tools.py
└── README.md           # Setup and usage instructions

For small servers (3-5 tools), a single server.py is fine. Don’t over-engineer the structure until you need it. Split into a tools/ directory when the server grows beyond 200-300 lines or when different tools have different dependencies.

The tests/ directory holds unit tests for your business logic — the actual database queries, API calls, and data processing. Test these independently from MCP, as described in MCP Server Testing and Debugging.

Next Steps After Setup

Once the server is running and connected:

1. Start small. One or two tools that wrap your most-queried system.
2. Iterate on descriptions. Watch how the AI uses your tools. If it picks the wrong tool, improve the description.
3. Add structured output. Move from string returns to Pydantic models as you identify which tools need consistent output formats. See MCP Tool Design Patterns.
4. Consider resources and prompts. If the AI needs read-only context (schemas, configs), add resources. If your team has repeatable workflows, add prompts.
5. Plan for production. When the server is useful enough to share, consider switching to HTTP transport for multi-user access.