Synapse MCP Server
Servidor Synapse MCP
Un servidor de Protocolo de contexto de modelo (MCP) que expone entidades de Synapse (conjuntos de datos, proyectos, carpetas, archivos, tablas) con sus anotaciones y admite la autenticación OAuth2.
Descripción general
Este servidor proporciona una API RESTful para acceder a las entidades de Synapse y sus anotaciones mediante el Protocolo de Contexto de Modelo (MCP). Permite:
Autenticarse con Synapse
Recuperar entidades por ID
Recuperar entidades por nombre
Obtener anotaciones de entidades
Obtener entidades hijas
Consultar entidades en función de varios criterios
Consultar tablas de Synapse
Obtener conjuntos de datos en formato de metadatos de Croissant
Related MCP server: Reactome MCP Server
Instalación
# 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 .Instalación desde PyPI
# Install from PyPI
pip install synapse-mcpUso
Iniciando el servidor
python server.py --host 127.0.0.1 --port 9000Esto iniciará el servidor MCP en el puerto predeterminado (9000).
Usando la CLI
# Start the server using the CLI
synapse-mcp --host 127.0.0.1 --port 9000 --debugOpciones de la línea de comandos
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)Ejecución de pruebas
# Run all tests with coverage
./run_tests.sh
# Or run pytest directly
python -m pytestProbando el servidor
python examples/client_example.pyMétodos de autenticación
Variables de entorno
El servidor admite las siguientes variables de entorno:
HOST: El host al que vincularse (predeterminado: 127.0.0.1)PORT: El puerto para escuchar (predeterminado: 9000)MCP_TRANSPORT: El protocolo de transporte a utilizar (predeterminado: stdio)stdio: utiliza entrada/salida estándar para el desarrollo localsse: Utilice eventos enviados por el servidor para la implementación en la nube
MCP_SERVER_URL: La URL pública del servidor (predeterminado: mcp://127.0.0.1:9000)Se utiliza para la redirección OAuth2 y la información del servidor.
El servidor admite dos métodos de autenticación:
Token de autenticación : autentique mediante un token de autenticación de Synapse
OAuth2 : Autenticación mediante el servidor OAuth2 de Synapse
Requiere registrar un cliente OAuth2 en Synapse ( https://www.synapse.org/#!PersonalAccessTokens:OAuth )
Puntos finales de API
Información del servidor
GET /info- Obtener información del servidor
Herramientas
GET /tools- Lista de herramientas disponiblesPOST /tools/authenticate- Autenticarse con SynapsePOST /tools/get_oauth_url- Obtener la URL de autorización de OAuth2POST /tools/get_entity- Obtener una entidad por ID o nombrePOST /tools/get_entity_annotations- Obtener anotaciones para una entidadPOST /tools/get_entity_children- Obtener entidades secundarias de una entidad contenedoraPOST /tools/query_entities- Consultar entidades según varios criteriosPOST /tools/query_table- Consultar una tabla de Synapse
Recursos
GET /resources- Lista de recursos disponiblesGET /resources/entity/{id}- Obtener la entidad por IDGET /resources/entity/{id}/annotations- Obtener anotaciones de entidadGET /resources/entity/{id}/children- Obtener hijos de la entidadGET /resources/query/entities/{entity_type}- Consultar entidades por tipoGET /resources/query/entities/parent/{parent_id}- Consultar entidades por ID principalGET /resources/query/entities/name/{name}- Consultar entidades por nombreGET /resources/query/table/{id}/{query}- Consulta una tabla con sintaxis similar a SQL
Puntos finales de OAuth2
GET /oauth/login- Redireccionar a la página de inicio de sesión de Synapse OAuth2GET /oauth/callback- Gestionar la devolución de llamada OAuth2 desde Synapse
Ejemplos
Autenticación
Debes autenticarte con credenciales reales de Synapse para usar el servidor:
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"
})Autenticación OAuth2
1. Flujo de redirección (basado en navegador)
Dirigir a los usuarios a la URL de inicio de sesión de OAuth:
http://127.0.0.1:9000/oauth/login?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI2. Flujo basado en API
Para uso programático, primero obtenga la URL de autorización:
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_urlObtener una entidad
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)Obtener anotaciones de entidades
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)Consulta de entidades
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)Consultar una tabla
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)Obtener conjuntos de datos en formato Croissant
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)Despliegue
Estibador
Puedes construir y ejecutar el servidor usando 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-mcpFly.io
Implementar en 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 deployIntegración con Claude Desktop
Puede integrar este servidor Synapse MCP con Claude Desktop para permitir que Claude acceda y trabaje con datos de Synapse directamente en sus conversaciones.
Instrucciones de configuración
Primero, clone el repositorio e instale los requisitos:
# 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 .Configurar Claude Desktop para utilizar el servidor Synapse MCP:
Abra Claude Desktop
Haga clic en el menú Claude y seleccione "Configuración..."
Haga clic en "Desarrollador" en la barra de la izquierda.
Haga clic en "Editar configuración"
Agregue la siguiente configuración a la sección
mcpServers:
"synapse-mcp": {
"command": "python",
"args": [
"/path/to/synapse-mcp/server.py",
"--host", "127.0.0.1",
"--port", "9000"
]
}Guarde el archivo de configuración y reinicie Claude Desktop
Ahora puedes usar los datos de Synapse en tus conversaciones con Claude. Por ejemplo:
Obtener la entidad con ID syn123456 de Synapse
Consultar todos los archivos del proyecto Synapse syn123456
Obtener anotaciones para la entidad Synapse syn123456
Contribuyendo
¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.
Licencia
Instituto Tecnológico de Massachusetts (MIT)
Available Tools
7 toolsget_datasets_as_croissantB
Get public datasets in Croissant metadata format.
Inputs: no named parameters. Returns: object
get_entityB
Get a Synapse entity by ID.
Inputs: entity_id (required). Returns: object
get_entity_annotationsC
Get annotations for an entity.
Inputs: entity_id (required). Returns: object
get_entity_childrenB
Get child entities of a container entity.
Inputs: entity_id (required). Returns: result
query_entitiesD
Query entities based on various criteria.
Inputs: annotations, entity_type, name, parent_id. Returns: result
query_tableC
Query a Synapse table.
Inputs: query (required), table_id (required). Returns: object
search_entitiesC
Search for Synapse entities.
Inputs: search_term (required), entity_type, parent_id. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have distinct purposes targeting different Synapse operations, but query_entities and search_entities could cause some confusion as both involve finding entities. The descriptions help differentiate them, with query_entities focusing on structured criteria and search_entities on broader search, but overlap exists.
Tool names follow a highly consistent verb_noun pattern throughout, using snake_case uniformly. All tools start with a clear verb (get, query, search) followed by a specific noun, making them predictable and easy to understand.
With 7 tools, this server is well-scoped for interacting with Synapse entities and datasets. Each tool serves a distinct function in the domain, such as retrieving entities, annotations, children, datasets, and querying/searching, without being overly sparse or bloated.
The tool set covers core read and query operations for Synapse entities and datasets effectively, including retrieval, annotation access, and searching. A minor gap exists in write operations (e.g., create, update, delete entities), but agents can likely work around this for many use cases.
Related MCP Connectors
Model Context Protocol server for Studex tools, notifications, and profile integrations
Siftable MCP server for governed work, knowledge, calendar, people, datasets, and Vault.
OAuth-protected, read-only-by-default MCP server for provenance-labeled QuillCaddie project memory.
MCP server for the GDEX (Geoscience Data Exchange) data portal: datasets, files, metrics, subsetting
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA server implementation of the Model Context Protocol (MCP) that provides REST API endpoints for managing and interacting with MCP resources.-
- AlicenseAqualityDmaintenanceModel Context Protocol server for accessing Reactome pathway and systems biology data.812MIT
- AlicenseBqualityDmaintenanceA production-ready Model Context Protocol (MCP) server that provides comprehensive access to the BioOntology API for searching, annotating, and exploring over 1,200 biological ontologies.1010MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that wraps the Accela Construct API as a curated, capability-grouped tool set for Accela Civic Platform, safe by default with read-only access.67 PyPI1Apache 2.0