# Fastn MCP Server

**Give your AI agents and apps secure, governed access to your customers' tools and systems through one multi-tenant MCP endpoint.**

Part of Fastn, the embedded integration platform for SaaS products and AI agents. Fastn MCP Server is a production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) gateway that connects AI agents and apps to Slack, Jira, GitHub, Salesforce, HubSpot, Postgres, and 200+ more services, with fully managed auth, governed multi-tenant access, and sub-second execution.

Built on the [Fastn SDK](https://github.com/fastn-ai/fastn-sdk), this server exposes MCP tools that any compatible AI platform can use out of the box.

## Why Fastn MCP Server?

| Feature | Description |
|---------|-------------|
| **250+ Connectors** | Slack, Jira, GitHub, Salesforce, HubSpot, Postgres, Stripe, Notion, Linear, and more |
| **MCP Native** | Works with Claude Desktop, Cursor, Lovable, Bolt, v0, and any MCP-compatible client |
| **Fully Managed Auth** | OAuth 2.1 for every connector, no token management, no app registration, no refresh handling |
| **Governed Access** | Role-based permissions, audit trails, and enterprise compliance controls |
| **SOC 2 Certified** | Enterprise-grade security and compliance built into the platform |
| **Sub-Second Execution** | Direct API calls through the Fastn platform with built-in caching and connection pooling |
| **Multiple Transports** | stdio (local), SSE, and Streamable HTTP for any deployment model |
| **Production Ready** | Docker support, health checks, structured logging, and OAuth 2.1 protected resource metadata |
| **Flow Automation** | Create, manage, and execute multi-step workflows that compose tools |

## Quick Start

### 1. Sign up at [app.fastn.ai](https://app.fastn.ai)

Create an account and connect your first connectors (Gmail, Slack, GitHub, etc.).

### 2. Connect your MCP client

**Hosted server (recommended)**, no installation needed:

```
https://mcp.live.fastn.ai/shttp
```

Point any MCP client at this URL. Authentication is handled via MCP OAuth 2.1 automatically. See [Client Configuration](#client-configuration) for Claude Desktop and Cursor examples.

**Self-hosted**, install and run your own instance:

```bash
pip install fastn-mcp-server
fastn-mcp --shttp --port 8000
```

## Connecting to the MCP Server

### Endpoints

Use the hosted server (`mcp.live.fastn.ai`) or your self-hosted instance. Each path exposes a different set of tools:

| Endpoint | Tools |
|----------|-------|
| `/shttp` | All 11 tools: `find_tools`, `execute_tool`, `list_connectors`, `list_skills`, `list_projects`, `list_flows`, `run_flow`, `delete_flow`, `create_flow`, `update_flow`, `configure_custom_auth` |
| `/shttp/tools` | 5 tools: `find_tools`, `execute_tool`, `list_connectors`, `list_skills`, `list_projects` |
| `/shttp/tools/{project_id}` | 4 tools: `find_tools`, `execute_tool`, `list_connectors`, `list_skills` |
| `/shttp/tools/{project_id}/{skill_id}` | 3 tools: `find_tools`, `execute_tool`, `list_connectors` |
| `/sse`, `/sse/tools`, etc. | Same pattern for SSE transport |

**Examples with the hosted server:**

```
https://mcp.live.fastn.ai/shttp                              # All tools
https://mcp.live.fastn.ai/shttp/tools                           # Fastn tools only
https://mcp.live.fastn.ai/shttp/tools/{project_id}              # Pre-set project
https://mcp.live.fastn.ai/shttp/tools/{project_id}/{skill_id}   # Pre-set project + skill
```

### Authentication

The MCP server supports three authentication methods. Get your credentials from [app.fastn.ai](https://app.fastn.ai).

#### MCP OAuth 2.1 (Recommended)

Standard MCP OAuth flow with PKCE. The server bridges to Fastn's identity provider automatically. Just point your client at the URL, you'll be prompted to authenticate:

```json
{
  "mcpServers": {
    "tools": {
      "url": "https://mcp.live.fastn.ai/shttp"
    }
  }
}
```

#### Token / API Key

Pass a Fastn auth token or API key via the `Authorization` header in your MCP client config:

```json
{
  "mcpServers": {
    "tools": {
      "url": "https://mcp.live.fastn.ai/shttp",
      "headers": {
        "Authorization": "Bearer <your-token-or-api-key>"
      }
    }
  }
}
```

You can also pass `x-project-id` to scope requests to a specific project:

```json
{
  "mcpServers": {
    "tools": {
      "url": "https://mcp.live.fastn.ai/shttp",
      "headers": {
        "Authorization": "Bearer <your-token-or-api-key>",
        "x-project-id": "<your-project-id>"
      }
    }
  }
}
```

For local stdio transport, pass credentials as environment variables:

```json
{
  "mcpServers": {
    "tools": {
      "command": "fastn-mcp",
      "args": ["--stdio"],
      "env": {
        "FASTN_API_KEY": "your-api-key",
        "FASTN_PROJECT_ID": "your-project-id"
      }
    }
  }
}
```

## MCP Tools

The server exposes these tools to AI agents:

### Fastn Tools

| Tool | Description |
|------|-------------|
| `find_tools` | Search for available connector tools by natural language prompt. Returns matching tools with IDs and input schemas. |
| `execute_tool` | Execute a connector tool by its ID with parameters. Returns the result directly. |
| `list_connectors` | Browse all 250+ available connectors in the registry, including ones not yet connected. |
| `list_skills` | List available skills in the project. |
| `list_projects` | List available projects for the authenticated user. |

**Workflow:** Browse connectors → `list_connectors`. Execute an action → `find_tools` → `execute_tool`. If `find_tools` returns nothing relevant → `list_connectors` (connector may need connecting).

### Flow Management

| Tool | Description |
|------|-------------|
| `list_flows` | List saved automations (flows) in the project. |
| `run_flow` | Execute a saved flow by its ID. |
| `delete_flow` | Remove a flow from the project. |
| `create_flow` | *(Under development)* Create a flow from natural language. |
| `update_flow` | *(Under development)* Update an existing flow. |

### Configuration

| Tool | Description |
|------|-------------|
| `configure_custom_auth` | Register a custom JWT auth provider (Auth0, Firebase, Supabase). |

## Architecture

```
AI Agent (Claude, Cursor, Lovable)
    │
    ▼
MCP Protocol (stdio / SSE / Streamable HTTP)
    │
    ▼
┌─────────────────────────────┐
│   Fastn MCP Server          │
│   ┌───────────────────────┐ │
│   │ Tool Discovery        │ │  find_tools, list_connectors
│   │ Tool Execution        │ │  execute_tool
│   │ Flow Management       │ │  list/run/delete/create flows
│   │ Auth & Config         │ │  OAuth 2.1, custom JWT
│   └───────────────────────┘ │
└─────────────────────────────┘
    │
    ▼
Fastn SDK → Fastn API
    │
    ▼
250+ Connectors (Slack, Jira, GitHub, Salesforce, Postgres, ...)
```

**Connectors** provide tools. **Flows** compose tools. **Agents** run flows and tools with reasoning.

## Client Configuration

The JSON examples above work with any MCP client. Here are the config file locations:

| Client | Config File |
|--------|------------|
| **Claude Desktop** | `claude_desktop_config.json` |
| **Cursor** | `.cursor/mcp.json` in your project |
| **Claude Code** | `.mcp.json` in your project |

For Cursor, use the `/shttp/tools` endpoint to expose only Fastn tools (recommended for coding assistants):

```json
{
  "mcpServers": {
    "tools": {
      "url": "https://mcp.live.fastn.ai/shttp/tools"
    }
  }
}
```

## Self-Hosting

### Transport Modes

**stdio (local)**, For pipe-based clients:

```bash
fastn-mcp --stdio
fastn-mcp --stdio --mode tools                          # Fastn tools only
fastn-mcp --stdio --mode tools --project ID              # Fastn tools + pre-set project
fastn-mcp --stdio --mode tools --project ID --skill ID   # Fastn tools + pre-set project and skill
```

**SSE + Streamable HTTP (remote)**, For web-based AI platforms:

```bash
fastn-mcp --sse --shttp --port 8000
```

### OAuth Setup

Remote transports use MCP OAuth 2.1 by default. The server implements RFC 9728 Protected Resource Metadata:

```bash
fastn-mcp --sse --shttp --port 8000
# OAuth endpoints auto-configured at /.well-known/oauth-protected-resource
```

Set the public URL for OAuth metadata:

```bash
fastn-mcp --sse --shttp --port 8000 --server-url https://mcp.example.com
```

To disable OAuth for local development:

```bash
fastn-mcp --sse --port 8000 --no-auth
```

### Docker

```bash
docker build -t fastn-mcp .
docker run -p 8000:8000 fastn-mcp
```

```bash
docker compose up -d
```

### Environment Variables

Server configuration for self-hosted deployments:

```bash
FASTN_MCP_PORT=8000
FASTN_MCP_HOST=0.0.0.0
FASTN_MCP_SERVER_URL=https://your-public-url
FASTN_MCP_TRANSPORT=both
FASTN_MCP_NO_AUTH=false
FASTN_MCP_VERBOSE=false
```

| Variable | Required | Description |
|----------|----------|-------------|
| `FASTN_MCP_PORT` | No | Server port (default: `8000`) |
| `FASTN_MCP_HOST` | No | Bind address (default: `0.0.0.0`) |
| `FASTN_MCP_SERVER_URL` | No | Public URL for OAuth metadata |
| `FASTN_MCP_NO_AUTH` | No | Set to `true` to disable OAuth (dev only) |
| `FASTN_MCP_TRANSPORT` | No | Transport mode: `sse`, `shttp`, `both` (default: `both`) |
| `FASTN_MCP_VERBOSE` | No | Set to `true` for debug logging |

### Local Development with ngrok

For local development and testing only, use ngrok to expose your local server:

```bash
# Terminal 1: Start the MCP server
fastn-mcp --shttp --port 8000 --verbose

# Terminal 2: Start ngrok tunnel
ngrok http 8000
```

Then restart with the ngrok URL so OAuth metadata resolves:

```bash
fastn-mcp --shttp --port 8000 \
  --server-url https://abc123.ngrok-free.dev \
  --verbose
```

For production, deploy with Docker behind a reverse proxy with a real domain.

## Development

### Setup

```bash
git clone https://github.com/fastn-ai/fastn-mcp.git
cd fastn-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest tests/ -q
```

### Project Structure

```
fastn-mcp/
├── fastn_mcp/
│   ├── __init__.py          # Package metadata
│   ├── __main__.py          # CLI entry point
│   ├── server.py            # MCP server, tools, handlers, routing
│   ├── auth.py              # OAuth 2.1 provider (RFC 9728)
│   └── tools/               # Tool utilities
├── tests/
│   ├── test_server.py       # 185+ tests covering all tools and transports
│   └── conftest.py          # Test fixtures
├── Dockerfile               # Production container
├── docker-compose.yml       # Docker Compose for deployment
├── pyproject.toml           # Python project configuration
└── README.md
```

## CLI Reference

```
fastn-mcp [OPTIONS]

Transport:
  --stdio          Use stdio transport (Claude Desktop, Cursor)
  --sse            Enable SSE transport
  --shttp          Enable Streamable HTTP transport

Server:
  --host HOST      Bind address (default: 0.0.0.0)
  --port PORT      Port number (default: 8000)
  --no-auth        Disable OAuth (development only)
  --server-url URL Public URL for OAuth metadata

Mode:
  --mode {agent,tools} Tool mode for stdio: "agent" (all tools) or "tools" (Fastn tools only)
  --project ID     Pre-set project ID for stdio
  --skill ID       Pre-set skill ID for stdio (requires --project)

Debug:
  -v, --verbose    Enable debug logging
```

## Supported Connectors

Fastn provides 250+ pre-built connectors including:

**Communication:** Slack, Microsoft Teams, Discord, Gmail, Outlook, SendGrid, Twilio

**Project Management:** Jira, Linear, Asana, Trello, Monday.com, ClickUp, Notion

**Development:** GitHub, GitLab, Bitbucket, PagerDuty, Sentry, Datadog

**CRM & Sales:** Salesforce, HubSpot, Pipedrive, Zoho CRM

**Databases:** PostgreSQL, MySQL, MongoDB, Redis, Supabase, Firebase

**Cloud:** AWS, Google Cloud, Azure, Cloudflare

**Finance:** Stripe, QuickBooks, Xero

**And 200+ more**, browse the full catalog at [fastn.ai/integrations](https://fastn.ai/integrations)

## License

MIT

## Links

- [Fastn Platform](https://fastn.ai)
- [Fastn SDK](https://github.com/fastn-ai/fastn-sdk)
- [MCP Specification](https://modelcontextprotocol.io/)
- [Documentation](https://docs.fastn.ai)