Configuration

This guide covers all configuration options available in guMCP, including environment variables, server settings, and authentication configuration.

Environment Variables

guMCP uses environment variables for configuration. These are stored in a .env file in the project root.

Creating Your Configuration File

If you haven’t already, create your .env file from the template:

cp .env.example .env

Core Configuration

ENVIRONMENT

string

default:"local"

Sets the runtime environment. Affects logging, error handling, and authentication behavior.

local - Development environment with verbose logging
production - Production environment with optimized settings

GUMCP_HOST

string

default:"0.0.0.0"

The host address the SSE server binds to.

0.0.0.0 - Listen on all network interfaces (accessible remotely)
127.0.0.1 - Listen on localhost only (local access only)

GUMCP_PORT

integer

default:"8000"

The port number the SSE server listens on.

GUMCP_PORT=8000

API Keys

ANTHROPIC_API_KEY

string

required

Your Anthropic API key for Claude. Required for running test clients.

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx

Get your API key from console.anthropic.com

Server-Specific Configuration

Each MCP server may require additional configuration. Authentication credentials are typically stored separately from the .env file.

API Key-Based Servers

These servers use simple API key authentication:

Perplexity

The Perplexity server requires an API key from perplexity.ai.Setup:

python src/servers/perplexity/main.py auth

You’ll be prompted to enter your API key, which will be stored in:

local_auth/credentials/perplexity/local_credentials.json

Features:

Web search with recency filters
Multiple model support (sonar, sonar-pro, sonar-deep-research)
Code assistance
Related questions retrieval

OAuth 2.0 Servers

These servers require OAuth 2.0 authentication setup:

Google Services (Sheets, Gmail, Docs, Drive, Calendar)

Google services require a Google Cloud Platform (GCP) project with OAuth 2.0 credentials.Prerequisites:

Create a project in Google Cloud Console
Enable the required APIs (Sheets API, Gmail API, etc.)
Create OAuth 2.0 credentials
Download the credentials JSON

Configuration: Create a configuration file at:

local_auth/oauth_configs/gsheets/oauth.json

With the following structure:

{
  "client_id": "your_client_id.apps.googleusercontent.com",
  "client_secret": "your_client_secret",
  "redirect_uri": "http://localhost:8080"
}

The default redirect URI http://localhost:8080 is recommended as it matches the OAuth utility in src/utils/oauth/util.py.

Supported Services:

Google Sheets (gsheets) - Read and write spreadsheet data
Gmail (gmail) - Send and read emails
Google Docs (gdocs) - Create and edit documents
Google Drive (gdrive) - Manage files and folders
Google Calendar (gcalendar) - Manage events and calendars

Alternative: Use Gumloop’s hosted MCP for seamless OAuth without local setup.

Slack

Slack uses OAuth 2.0 without refresh tokens.Prerequisites:

Create a Slack app at api.slack.com/apps
Configure OAuth & Permissions
Add required scopes
Install the app to your workspace

Configuration:

local_auth/oauth_configs/slack/oauth.json

{
  "client_id": "your_slack_client_id",
  "client_secret": "your_slack_client_secret",
  "redirect_uri": "http://localhost:8080"
}

Local OAuth setup requires an HTTPS redirect URI for production. Use ngrok or similar for local development with real Slack workspaces.

Reference Implementation: See src/utils/slack/util.py

Outlook

Outlook requires Azure app registration.Prerequisites:

Register an app in Azure Portal
Configure Microsoft Graph API permissions
Add redirect URI
Generate client secret

Configuration:

local_auth/oauth_configs/outlook/oauth.json

{
  "client_id": "your_azure_client_id",
  "client_secret": "your_azure_client_secret",
  "redirect_uri": "http://localhost:8080"
}

Airtable

Airtable uses OAuth 2.0 with refresh tokens and PKCE (Proof Key for Code Exchange).Prerequisites:

Create an Airtable OAuth integration at airtable.com/create/oauth
Configure redirect URI
Note your client ID and client secret

Configuration:

local_auth/oauth_configs/airtable/oauth.json

{
  "client_id": "your_airtable_client_id",
  "client_secret": "your_airtable_client_secret",
  "redirect_uri": "http://localhost:8080"
}

Reference Implementation: See src/utils/airtable/util.py for PKCE flow example

Linear

Linear uses OAuth 2.0 for project management integration.Prerequisites:

Create an OAuth application in Linear settings
Configure redirect URI
Note your client ID and client secret

Configuration:

local_auth/oauth_configs/linear/oauth.json

{
  "client_id": "your_linear_client_id",
  "client_secret": "your_linear_client_secret",
  "redirect_uri": "http://localhost:8080"
}

Attio

Attio CRM uses OAuth 2.0 with refresh tokens and additional token response parameters.Prerequisites:

Create an Attio OAuth application
Configure redirect URI
Note your client ID and client secret

Configuration:

local_auth/oauth_configs/attio/oauth.json

{
  "client_id": "your_attio_client_id",
  "client_secret": "your_attio_client_secret",
  "redirect_uri": "http://localhost:8080"
}

Reference Implementation: See src/utils/attio/util.py for handling additional token parameters

File Structure

understanding where configuration and credentials are stored:

guMCP/
├── .env                          # Main environment variables
├── .env.example                  # Environment template
├── local_auth/
│   ├── credentials/              # Stored user credentials
│   │   ├── perplexity/
│   │   │   └── local_credentials.json
│   │   ├── gsheets/
│   │   │   └── local_credentials.json
│   │   └── slack/
│   │       └── local_credentials.json
│   └── oauth_configs/            # OAuth application configs
│       ├── gsheets/
│       │   └── oauth.json
│       ├── slack/
│       │   └── oauth.json
│       └── airtable/
│           └── oauth.json
└── src/
    └── servers/
        └── {server-name}/
            └── README.md         # Server-specific docs

Never commit the local_auth/ directory or .env file to version control. These contain sensitive credentials.

Server Startup Configuration

The start_sse_dev_server.sh script handles server startup with the following behavior:

Load environment variables

Loads all variables from .env if the file exists

Set defaults

Sets default values for GUMCP_HOST (0.0.0.0) and GUMCP_PORT (8000) if not configured

Kill existing process

Checks if any process is using the configured port and kills it

Start server

Launches the main server: python src/servers/main.py

Manual Server Startup

You can also start the server manually with custom arguments:

python src/servers/main.py --host 127.0.0.1 --port 3000

--host

string

default:"0.0.0.0"

Server host address

--port

integer

default:"8000"

Server port number

Production Configuration

For production deployments, consider these additional configurations:

Environment Settings

.env

# Production environment
ENVIRONMENT=production

# Restrict to localhost if behind reverse proxy
GUMCP_HOST=127.0.0.1
GUMCP_PORT=8000

# Required: Anthropic API key
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx

Reverse Proxy

When running behind nginx or another reverse proxy:

nginx.conf

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Process Management

Use a process manager to keep guMCP running:

[Unit]
Description=guMCP Server
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/guMCP
Environment="PATH=/path/to/guMCP/venv/bin"
ExecStart=/path/to/guMCP/venv/bin/python src/servers/main.py
Restart=always

[Install]
WantedBy=multi-user.target

Security Best Practices

guMCP handles sensitive credentials and API access. Follow these security practices:

Never commit credentials - Add local_auth/ and .env to .gitignore
Use environment-specific keys - Separate keys for development and production
Restrict access - Use GUMCP_HOST=127.0.0.1 when behind a reverse proxy
Enable HTTPS - Always use HTTPS in production with valid SSL certificates
Rotate keys regularly - Update API keys and OAuth secrets periodically
Monitor access - Log and monitor API usage for unusual activity
Limit OAuth scopes - Only request necessary permissions for OAuth apps

Gumloop is SOC 2 Type II, GDPR, and HIPAA compliant. For production deployments requiring compliance, consider using Gumloop’s hosted MCP servers.

Authentication Reference

For developers implementing new servers or custom authentication:

OAuth 2.0 Implementation

Reference implementations for different OAuth patterns:

Simple OAuth (no refresh): src/utils/slack/util.py
OAuth with refresh tokens: src/utils/attio/util.py
OAuth with PKCE: src/utils/airtable/util.py

API Key Implementation

Reference implementation: src/servers/perplexity/main.py

Custom Auth Client

If implementing a custom AuthClient for remote hosting:

Extend BaseAuthClient from src/auth/clients/BaseAuthClient.py
Implement get_user_credentials() to return refreshed credentials
Handle token refresh internally within your client

See CONTRIBUTING.MD for detailed authentication implementation guidelines.

Troubleshooting

Environment variables not loading

Ensure:

.env file exists in project root
File is properly formatted (no spaces around =)
No quotes needed around values
File is not named .env.txt or .env.example

Test loading:

source .env && echo $ANTHROPIC_API_KEY

OAuth authentication failing

Common issues:

Redirect URI mismatch - Must match exactly in OAuth config and provider settings
Missing scopes - Ensure all required scopes are configured
Expired credentials - Delete old credentials and re-authenticate
Localhost vs 127.0.0.1 - Some providers are strict about localhost vs IP
HTTPS required - Production OAuth may require HTTPS redirect URIs

Port already in use

The startup script automatically kills processes on the configured port. If issues persist:

# Manually kill process on port 8000
lsof -ti :8000 | xargs kill -9

# Or use a different port
GUMCP_PORT=3000 ./start_sse_dev_server.sh

Credentials not persisting

Check:

local_auth/ directory exists and is writable
Server-specific subdirectories exist (e.g., local_auth/credentials/perplexity/)
No file permission issues
Authentication command completed successfully

Overview

Getting Started

Core Concepts

Deployment

Development

Configuration

Environment Variables

Creating Your Configuration File

Core Configuration

API Keys

Server-Specific Configuration

API Key-Based Servers

OAuth 2.0 Servers

File Structure

Server Startup Configuration

Manual Server Startup

Production Configuration

Environment Settings

Reverse Proxy

Process Management

Security Best Practices

Authentication Reference

OAuth 2.0 Implementation

API Key Implementation

Custom Auth Client

Troubleshooting

Next Steps

Server Documentation

Contributing

Build docs developers (and LLMs) love

Overview

Getting Started

Core Concepts

Deployment

Development

Documentation Index

​Environment Variables

​Creating Your Configuration File

​Core Configuration

​API Keys

​Server-Specific Configuration

​API Key-Based Servers

​OAuth 2.0 Servers

​File Structure

​Server Startup Configuration

​Manual Server Startup

​Production Configuration

​Environment Settings

​Reverse Proxy

​Process Management

​Security Best Practices

​Authentication Reference

​OAuth 2.0 Implementation

​API Key Implementation

​Custom Auth Client

​Troubleshooting

​Next Steps

Server Documentation

Contributing

Build docs developers (and LLMs) love

Environment Variables

Creating Your Configuration File

Core Configuration

API Keys

Server-Specific Configuration

API Key-Based Servers

OAuth 2.0 Servers

File Structure

Server Startup Configuration

Manual Server Startup

Production Configuration

Environment Settings

Reverse Proxy

Process Management

Security Best Practices

Authentication Reference

OAuth 2.0 Implementation

API Key Implementation

Custom Auth Client

Troubleshooting

Next Steps