Unified Context Layer (UCL) MCP Gateway
Unified Context Layer (UCL) is a multi-tenant Model Context Protocol (MCP) server that enables AI agents, automation platforms, and applications to connect to over 1,000 SaaS tools—such as Slack, Jira, Gmail, Shopify, Notion, and more—via a single standardized /command endpoint. UCL abstracts away SDK sprawl, glue code, and complex authentication flows, allowing developers to orchestrate context-rich, cross-platform integrations without building and maintaining separate connectors for each service.
Features
- Integrated platform support - Use services like Slack, Notion, HubSpot, and more through the Fastn server
- Flexible authentication - Use either API key or tenant-based authentication
- Comprehensive logging - Detailed logs for troubleshooting
- Error handling - Robust error management for various scenarios
Prerequisites
- Python 3.10 or higher
Installation Options
Option 1: Package Installation (Recommended)
The easiest way to install the UCL server is using pip:
pip install fastn-mcp-server
To find the exact path of the installed command:
- On macOS/Linux:
which fastn-mcp-server - On Windows:
where fastn-mcp-server
After Package Installation
{
"mcpServers": {
"fastn": {
"command": "fastn-mcp-server",
"args": [
"--api_key",
"YOUR_API_KEY",
"--space_id",
"YOUR_WORKSPACE_ID"
]
}
}
}
Option 2: Manual Setup
# Clone repository and navigate to directory
git clone <your-repo-url> && cd fastn-server
# macOS/Linux: Install UV, create virtual environment, and install dependencies
curl -LsSf https://astral.sh/uv/install.sh | sh && uv venv && source .venv/bin/activate && uv pip install -e .
# Windows (PowerShell): Install UV, create a virtual environment, and install dependencies
powershell -c "irm https://astral.sh/uv/install.ps1 | iex" && uv venv && .venv\Scripts\activate && uv pip install -e .
# Install dependencies directly
uv pip install "httpx>=0.28.1" "mcp[cli]>=1.2.0"
UCL Account Setup
- Log in to your UCL account or sign up for a new UCL account
- Activate the service(s)/connector(s) you want to use
- Go to the "Integrate" section on the left-hand side and follow the provided instructions to connect UCL to your agents.
- Alternatively, you can also select and different method to use UCL as mentioned within the integrate section.
Running the Server
The server supports two authentication methods:
Authentication Method 1: API Key
# Package installation
fastn-mcp-server --api_key YOUR_API_KEY --space_id YOUR_WORKSPACE_ID
# Manual installation
uv run fastn-server.py --api_key YOUR_API_KEY --space_id YOUR_WORKSPACE_ID
Authentication Method 2: Tenant-based
# Package installation
fastn-mcp-server --space_id YOUR_WORKSPACE_ID --tenant_id YOUR_TENANT_ID --auth_token YOUR_AUTH_TOKEN
# Manual installation
uv run fastn-server.py --space_id YOUR_WORKSPACE_ID --tenant_id YOUR_TENANT_ID --auth_token YOUR_AUTH_TOKEN
Integration with AI Assistants
Claude Integration
-
Open the Claude configuration file:
- Windows:
notepad "%APPDATA%\Claude\claude_desktop_config.json"orcode "%APPDATA%\Claude\claude_desktop_config.json" - Mac:
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
- Windows:
-
Add the appropriate configuration:
Using Package Installation
{
"mcpServers": {
"fastn": {
"command": "/path/to/fastn-mcp-server",
"args": [
"--api_key",
"YOUR_API_KEY",
"--space_id",
"YOUR_WORKSPACE_ID"
]
}
}
}
Or with tenant authentication:
{
"mcpServers": {
"fastn": {
"command": "/path/to/fastn-mcp-server",
"args": [
"--space_id",
"YOUR_WORKSPACE_ID",
"--tenant_id",
"YOUR_TENANT_ID",
"--auth_token",
"YOUR_AUTH_TOKEN"
]
}
}
}
Using Manual Installation
API Key authentication:
{
"mcpServers": {
"fastn": {
"command": "/path/to/your/uv",
"args": [
"--directory",
"/path/to/your/fastn-server",
"run",
"fastn-server.py",
"--api_key",
"YOUR_API_KEY",
"--space_id",
"YOUR_WORKSPACE_ID"
]
}
}
}
Tenant authentication:
{
"mcpServers": {
"fastn": {
"command": "/path/to/your/uv",
"args": [
"--directory",
"/path/to/your/fastn-server",
"run",
"fastn-server.py",
"--space_id",
"YOUR_WORKSPACE_ID",
"--tenant_id",
"YOUR_TENANT_ID",
"--auth_token",
"YOUR_AUTH_TOKEN"
]
}
}
}
Cursor Integration
- Open Cursor settings
- Navigate to the "Tools & Integrations" tab and click "Add Custom MCP"
- Click on "Add new MCP server"
- Add a name for your server (e.g., "fastn")
- Head back to UCL and within the Integrate section, head over to "Real Time Event Streaming" mentioned at the bottom of the Integrate section
- Copy the JSON command and head back to Cursor to paste the file in mcp.json and save.
Docker Integration
Step 1: Setup Environment Configuration
Create a .env file in your project directory with your UCL credentials:
# Configuration Format 1: Basic API Key and Space ID
API_KEY=your_actual_api_key
SPACE_ID=your_actual_space_id
# Configuration Format 2: Extended with Tenant ID and Auth Token
TENANT_ID=your_tenant_id
AUTH_TOKEN=your_actual_auth_token
# Set configuration mode: "basic" or "extended"
CONFIG_MODE=extended
Step 2: Build and Run with Docker Compose
First, build and start the container:
docker-compose up --build
This will create the UCL server image and verify it starts correctly.
Step 3: Configure AI Assistants for Docker Integration
Claude Desktop Integration
-
Open the Claude configuration file:
- Windows:
notepad "%APPDATA%\Claude\claude_desktop_config.json" - Mac:
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
- Windows:
-
Add the Docker configuration:
{
"mcpServers": {
"ucl": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"--env-file", "/path/to/your/fastn-stdio-server/.env",
"ucl-stdio-server"
]
}
}
}
Note: Replace /path/to/your/fastn-stdio-server/.env with the actual path to your .env file.
Alternative: Using Environment Variables
If you prefer to pass environment variables directly:
{
"mcpServers": {
"ucl": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "API_KEY=your_actual_api_key",
"-e", "SPACE_ID=your_actual_space_id",
"-e", "TENANT_ID=your_tenant_id",
"-e", "AUTH_TOKEN=your_actual_auth_token",
"-e", "CONFIG_MODE=extended",
"ucl-stdio-server"
]
}
}
}
Benefits of Docker Integration
- Isolation: UCL server runs in a secure container environment
- Consistency: Same runtime across different machines and platforms
- Easy Setup: No need to install Python dependencies locally
- Scalability: Can be deployed in cloud environments or orchestrated with Kubernetes
Troubleshooting
Package Structure Error
If you encounter an error like this during installation:
ValueError: Unable to determine which files to ship inside the wheel using the following heuristics:
The most likely cause of this is that there is no directory that matches the name of your project (fastn).
Quick Fix:
- Make sure
pyproject.tomlhas the wheel configuration:
[tool.hatch.build.targets.wheel]
packages = ["."]
- Then install dependencies:
uv pip install "httpx>=0.28.1" "mcp[cli]>=1.2.0"
Support
- Documentation: https://docs.fastn.ai/ucl-unified-context-layer/about-ucl
- Community: https://discord.gg/Nvd5p8axU3
License
This project is licensed under the terms included in the LICENSE file.