Synapse MCP Server

A Model Context Protocol (MCP) server that exposes Synapse Entities (Datasets, Projects, Folders, Files, Tables) with their annotations and supports OAuth2 authentication.

Overview

This server provides a RESTful API for accessing Synapse entities and their annotations through the Model Context Protocol (MCP). It allows you to:

Authenticate with Synapse
Retrieve entities by ID
Retrieve entities by name
Get entity annotations
Get entity children
Query entities based on various criteria
Query Synapse tables
Get datasets in Croissant metadata format

Installation

# Clone the repository
git clone https://github.com/SageBionetworks/synapse-mcp.git
cd synapse-mcp

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

Installing from PyPI

# Install from PyPI
pip install synapse-mcp

Usage

Starting the Server

python server.py --host 127.0.0.1 --port 9000

This will start the MCP server on the default port (9000).

Using the CLI

# Start the server using the CLI
synapse-mcp --host 127.0.0.1 --port 9000 --debug

Command-line Options

usage: server.py [-h] [--host HOST] [--port PORT] [--debug]

Run the Synapse MCP server with OAuth2 support

options:
  -h, --help       show this help message and exit
  --host HOST      Host to bind to
  --port PORT      Port to listen on
  --debug          Enable debug logging
  --server-url URL Public URL of the server (for OAuth2 redirect)

Running Tests

# Run all tests with coverage
./run_tests.sh

# Or run pytest directly
python -m pytest

Testing the Server

python examples/client_example.py

Authentication Methods

Environment Variables

The server supports the following environment variables:

HOST: The host to bind to (default: 127.0.0.1)
PORT: The port to listen on (default: 9000)
MCP_TRANSPORT: The transport protocol to use (default: stdio)
- stdio: Use standard input/output for local development
- sse: Use Server-Sent Events for cloud deployment
MCP_SERVER_URL: The public URL of the server (default: mcp://127.0.0.1:9000)
- Used for OAuth2 redirect and server information

The server supports two authentication methods:

Auth Token: Authenticate using a Synapse authentication token
OAuth2: Authenticate using Synapse's OAuth2 server
- Requires registering an OAuth2 client in Synapse (https://www.synapse.org/#!PersonalAccessTokens:OAuth)

API Endpoints

Server Information

GET /info - Get server information

Tools

GET /tools - List available tools
POST /tools/authenticate - Authenticate with Synapse
POST /tools/get_oauth_url - Get the OAuth2 authorization URL
POST /tools/get_entity - Get an entity by ID or name
POST /tools/get_entity_annotations - Get annotations for an entity
POST /tools/get_entity_children - Get child entities of a container entity
POST /tools/query_entities - Query entities based on various criteria
POST /tools/query_table - Query a Synapse table

Resources

GET /resources - List available resources
GET /resources/entity/{id} - Get entity by ID
GET /resources/entity/{id}/annotations - Get entity annotations
GET /resources/entity/{id}/children - Get entity children
GET /resources/query/entities/{entity_type} - Query entities by type
GET /resources/query/entities/parent/{parent_id} - Query entities by parent ID
GET /resources/query/entities/name/{name} - Query entities by name
GET /resources/query/table/{id}/{query} - Query a table with SQL-like syntax

OAuth2 Endpoints

GET /oauth/login - Redirect to Synapse OAuth2 login page
GET /oauth/callback - Handle OAuth2 callback from Synapse

Examples

Authentication

You need to authenticate with real Synapse credentials to use the server:

import requests

# Authenticate with Synapse
response = requests.post("http://127.0.0.1:9000/tools/authenticate", json={
    "email": "your-synapse-email@example.com",
    "password": "your-synapse-password"
})
result = response.json()
print(result)

# Alternatively, you can authenticate with an API key
response = requests.post("http://127.0.0.1:9000/tools/authenticate", json={
    "api_key": "your-synapse-api-key"
})

OAuth2 Authentication

1. Redirect Flow (Browser-based)

Direct users to the OAuth login URL:

http://127.0.0.1:9000/oauth/login?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

2. API-based Flow

For programmatic use, first get the authorization URL:

import requests

# Get OAuth2 authorization URL
response = requests.post("http://127.0.0.1:9000/tools/get_oauth_url", json={
    "client_id": "YOUR_CLIENT_ID",
    "redirect_uri": "YOUR_REDIRECT_URI"
})
auth_url = response.json()["auth_url"]
# Redirect user to auth_url

Getting an Entity

import requests

# Get an entity by ID
response = requests.get("http://127.0.0.1:9000/resources/entity/syn123456")  # Replace with a real Synapse ID
entity = response.json()
print(entity)

Getting Entity Annotations

import requests

# Get annotations for an entity
response = requests.get("http://127.0.0.1:9000/resources/entity/syn123456/annotations")  # Replace with a real Synapse ID
annotations = response.json()
print(annotations)

Querying Entities

import requests

# Query for files in a project
response = requests.get("http://127.0.0.1:9000/resources/query/entities/parent/syn123456", params={  # Replace with a real Synapse ID
    "entity_type": "file"
})
files = response.json()
print(files)

Querying a Table

import requests

# Query a table
table_id = "syn123456"  # Replace with a real Synapse table ID
query = "SELECT * FROM syn123456 LIMIT 10"  # Replace with a real Synapse table ID
response = requests.get(f"http://127.0.0.1:9000/resources/query/table/{table_id}/{query}")
table_data = response.json()
print(table_data)

Getting Datasets in Croissant Format

import requests
import json

# Get public datasets in Croissant format
response = requests.get("http://127.0.0.1:9000/resources/croissant/datasets")
croissant_data = response.json()

# Save to file
with open("croissant_metadata.json", "w") as f:
    json.dump(croissant_data, f, indent=2)

Deployment

Docker

You can build and run the server using Docker:

# Build the Docker image
docker build -t synapse-mcp .

# Run the container
docker run -p 9000:9000 -e SYNAPSE_OAUTH_CLIENT_ID=your_client_id -e SYNAPSE_OAUTH_CLIENT_SECRET=your_client_secret -e SYNAPSE_OAUTH_REDIRECT_URI=your_redirect_uri synapse-mcp
docker run -p 9000:9000 -e MCP_TRANSPORT=sse -e MCP_SERVER_URL=mcp://your-domain:9000 synapse-mcp

Fly.io

Deploy to fly.io:

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Login to fly.io
flyctl auth login

# Launch the app
flyctl launch

# Set OAuth2 secrets
flyctl secrets set SYNAPSE_OAUTH_CLIENT_ID=your_client_id
flyctl secrets set SYNAPSE_OAUTH_CLIENT_SECRET=your_client_secret
flyctl secrets set SYNAPSE_OAUTH_REDIRECT_URI=https://your-app-name.fly.dev/oauth/callback
flyctl secrets set MCP_TRANSPORT=sse
flyctl secrets set MCP_SERVER_URL=mcp://your-app-name.fly.dev:9000

# Deploy
flyctl deploy

Integrating with Claude Desktop

You can integrate this Synapse MCP server with Claude Desktop to enable Claude to access and work with Synapse data directly in your conversations.

Setup Instructions

First, clone the repository and install the requirements:

# Clone the repository
git clone https://github.com/susheel/synapse-mcp.git
cd synapse-mcp

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

Configure Claude Desktop to use the Synapse MCP server:
- Open Claude Desktop
- Click on the Claude menu and select "Settings..."
- Click on "Developer" in the left-hand bar
- Click on "Edit Config"
- Add the following configuration to the mcpServers section:

"synapse-mcp": {
  "command": "python",
  "args": [
    "/path/to/synapse-mcp/server.py",
    "--host", "127.0.0.1",
    "--port", "9000"
  ]
}

Save the configuration file and restart Claude Desktop
You can now use Synapse data in your conversations with Claude. For example:
- "Get the entity with ID syn123456 from Synapse"
- "Query all files in the Synapse project syn123456"
- "Get annotations for the Synapse entity syn123456"

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Integrations