Skip to main content
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
FilePurpose
config.yamlDeclares your server’s name, auth type, and which tools to expose
src/server.pyWhere you define your tools using FastMCP
src/utils/auth.pyHelper for retrieving user credentials
.envLocal environment variables for development
pyproject.tomlPython 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