Skip to main content
In this guide, you’ll create and deploy your first MCP (Model Context Protocol) server using Gumstack. By the end, you’ll have a working server with a custom tool that AI assistants like Claude, Cursor, and others can use, all deployed and ready in minutes.

​
Prerequisites

Before you start building, make sure you have:
  • GitHub connected in Settings. Gumstack needs this to create and manage your server’s repository.
  • GitHub App installed for automatic deployments on push.
  • Python 3.10+ and uv (recommended) or pip installed locally.
If you haven’t connected GitHub yet, head to Settings first.

​
Create your server

1

Open the Create Server wizard

Go to Internal MCPs and click Create New Server. This opens a full-screen wizard that walks you through setup.
2

Enter basic info

Give your server a name and description. Select your GitHub organization and a repository name. Gumstack validates the repository name in real-time to ensure it’s available.
Create server basic info
FieldDescription
Server nameDisplay name shown in the Gumstack dashboard
DescriptionBrief explanation of what the server does
GitHub Owner/OrgWhich GitHub org to create the repo in
Repository NameMust be unique, alphanumeric with -_.
VisibilityPublic, private, or internal
3

Configure authentication

Choose how users will authenticate with your server. This determines how your MCP server accesses external services on behalf of users.
Authentication settings
Auth TypeUse when
OAuth 2.0Users authorize via OAuth flow (Linear, GitHub, Slack, etc.)
API Key / CredentialsUsers enter their own API keys in the Gumstack UI
No AuthenticationYou provide shared keys via environment variables
You can also add environment variables for any secrets your server needs at runtime (e.g., CLIENT_SECRET, API_BASE_URL).
4

Review and create

Double-check your configuration. Each section has an Edit button to jump back and make changes. Click Create to generate everything.
Review configuration
Gumstack will:
  1. Create a GitHub repository with the full project template
  2. Set up the CI/CD deployment pipeline
  3. Configure authentication based on your selection
5

Install the GitHub App (if prompted)

If the Gumloop GitHub App isn’t installed on your new repository, you’ll see a prompt to install it. This enables automatic deployments when you push code.You can skip this and set it up later in Settings, but deployments won’t be automatic until it’s installed.

​
Clone and install

Clone the repository Gumstack created and install dependencies. 
git clone https://github.com/your-org/your-server.git
cd your-server

​
Add your first tool

Tools are the functions your MCP server exposes to AI assistants. Each tool has a name, description, and logic that the AI can invoke. Edit src/server.py: 
from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel

mcp = FastMCP("my-server")

class GreetingResponse(BaseModel):
    message: str

@mcp.tool()
def greet(name: str) -> GreetingResponse:
    """Say hello to someone."""
    return GreetingResponse(message=f"Hello, {name}!")
Register your tool in config.yaml so Gumstack knows to expose it: 
tools:
  - name: "greet"
    description: "Say hello to someone"
Every tool needs both a Python function and a config.yaml entry. Without the config entry, Gumstack won’t detect the tool. See Tools for best practices.

​
Deploy

Push your code to trigger an automatic deployment: 
git add .
git commit -m "Add greet tool"
git push
Gumstack watches your repository and automatically builds and deploys your server whenever you push to main. You can monitor the deployment from the Deployments tab on your server’s detail page.
Your server is live! You can find its URL on the server’s Overview tab in Internal MCPs.

​
What’s next?

Project Structure

Understand your server’s file layout

Tools

Learn tool best practices and patterns

Authentication

Implement OAuth, credentials, or env vars

Using in Gumloop

Connect your server to Gumloop workflows