Project Structure

The repository you cloned has everything you need to start building your MCP server—authentication, deployment configuration, and a ready-to-use project structure. Here’s what’s inside and where to find things.

Overview

When you create a server, Gumstack generates this structure:

your-server/
├── config.yaml          # Server metadata and tool declarations
├── src/
│   ├── server.py        # FastMCP server and tool definitions
│   └── utils/
│       └── auth.py      # get_credentials() helper
├── tests/               # pytest tests
├── .env                 # Local environment variables
└── pyproject.toml       # Dependencies

File	Purpose
`config.yaml`	Declares your server’s name, auth type, and which tools to expose
`src/server.py`	Where you define your tools using FastMCP
`src/utils/auth.py`	Helper for retrieving user credentials
`.env`	Local environment variables for development
`pyproject.toml`	Python dependencies managed by uv or pip

gumstack-mcp is a fork of the official MCP Python SDK. All upstream features are supported, including both FastMCP (high-level) and the low-level Server API.

config.yaml

Server configuration and tool declarations. Tools must be listed here to be detected by Gumstack.

name: "my-server"
description: "What this server does"

auth:
  type: cred # oauth | cred | none
  credentials:
    - name: "api_key"
      label: "API Key"
      secret: true

tools:
  - name: "my_tool"
    description: "What this tool does"

See config.yaml reference for all options.

src/server.py

Your FastMCP server and tool definitions. This is where you’ll spend most of your time building tools.

from mcp.server.fastmcp import FastMCP
from src.utils.auth import get_credentials

mcp = FastMCP("my-server")

@mcp.tool()
async def my_tool(query: str) -> str:
    """Tool description shown to LLMs."""
    creds = await get_credentials()
    # Use creds["api_key"] to call external API
    return f"Result for {query}"

For more on building tools, see Tools.

src/utils/auth.py

Credential retrieval helper. The implementation depends on your auth type:

# For oauth/cred types (async)
async def get_credentials() -> dict[str, str]:
    if os.environ.get("ENVIRONMENT") == "local":
        return {"api_key": os.environ.get("LOCAL_API_KEY", "")}

    from mcp.gumstack import get_credentials as gumstack_get_credentials
    return await gumstack_get_credentials()

# For none type (sync)
def get_credentials() -> dict[str, str]:
    return {"api_key": os.environ.get("API_KEY", "")}

.env

Local development environment variables:

ENVIRONMENT=local
LOCAL_API_KEY=your-test-key

Never commit .env to git. It’s in .gitignore by default.

Quick Reference

Common commands you’ll use during development:

uv sync          # Install dependencies
uv run server    # Run locally
uv run pytest    # Run tests
uv add httpx     # Add a package

Get Started

Platform

Building Servers

Security

Deployment

Reference

Project Structure

Overview

config.yaml

src/server.py

src/utils/auth.py

.env

Quick Reference

​Overview

​config.yaml

​src/server.py

​src/utils/auth.py

​.env

​Quick Reference

Overview

config.yaml

src/server.py

src/utils/auth.py

.env

Quick Reference