Skip to main content
Glama
enesjakozh
susheel

Synapse MCP Server

by susheel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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-mcp

Uso

Iniciando el servidor

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

Esto 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 --debug

Opciones 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 pytest

Probando el servidor

python examples/client_example.py

Mé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 local

    • sse : 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:

  1. Token de autenticación : autentique mediante un token de autenticación de Synapse

  2. OAuth2 : Autenticación mediante el servidor OAuth2 de Synapse

Puntos finales de API

Información del servidor

  • GET /info - Obtener información del servidor

Herramientas

  • GET /tools - Lista de herramientas disponibles

  • POST /tools/authenticate - Autenticarse con Synapse

  • POST /tools/get_oauth_url - Obtener la URL de autorización de OAuth2

  • POST /tools/get_entity - Obtener una entidad por ID o nombre

  • POST /tools/get_entity_annotations - Obtener anotaciones para una entidad

  • POST /tools/get_entity_children - Obtener entidades secundarias de una entidad contenedora

  • POST /tools/query_entities - Consultar entidades según varios criterios

  • POST /tools/query_table - Consultar una tabla de Synapse

Recursos

  • GET /resources - Lista de recursos disponibles

  • GET /resources/entity/{id} - Obtener la entidad por ID

  • GET /resources/entity/{id}/annotations - Obtener anotaciones de entidad

  • GET /resources/entity/{id}/children - Obtener hijos de la entidad

  • GET /resources/query/entities/{entity_type} - Consultar entidades por tipo

  • GET /resources/query/entities/parent/{parent_id} - Consultar entidades por ID principal

  • GET /resources/query/entities/name/{name} - Consultar entidades por nombre

  • GET /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 OAuth2

  • GET /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_URI

2. 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_url

Obtener 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-mcp

Fly.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 deploy

Integració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

  1. 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 .

  1. 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"
  ]
}

  1. Guarde el archivo de configuración y reinicie Claude Desktop

  2. 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 tools
get_datasets_as_croissantB

Get public datasets in Croissant metadata format.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves public datasets, implying a read-only operation, but doesn't clarify aspects like authentication requirements, rate limits, or what 'public' entails. More context on behavior is needed for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It's front-loaded and appropriately sized for a simple tool with no parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, output schema provided), the description is adequate but minimal. It lacks details on behavioral traits and usage context, which could be important for an agent to operate effectively, especially without annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, but this is acceptable given the schema's completeness, aligning with the baseline for zero parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and resource ('public datasets in Croissant metadata format'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its siblings (like get_entity or query_entities), which might also retrieve data but in different formats or scopes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, context for use, or comparisons to sibling tools, leaving the agent to infer usage based on the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_entityB

Get a Synapse entity by ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
entity_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'Get[s]' an entity, implying a read operation, but doesn't specify whether it's safe, requires authentication, has rate limits, or what happens if the ID is invalid. For a tool with zero annotation coverage, this leaves critical behavioral traits undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—a single sentence with no wasted words. It's front-loaded with the core purpose, making it easy to parse. Every word earns its place, and there's no redundancy or unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one parameter) and the presence of an output schema (which handles return values), the description is minimally complete. However, it lacks context about Synapse entities and doesn't differentiate from siblings, leaving gaps in understanding when and how to use it effectively. It's adequate but with clear room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning by specifying that the 'entity_id' parameter is used to retrieve a Synapse entity, which clarifies the parameter's purpose beyond the schema's basic 'Entity Id' title. With 0% schema description coverage and only one parameter, this minimal addition is sufficient to compensate, earning a baseline 4 for adequate coverage in this simple case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool's purpose ('Get a Synapse entity by ID'), which is clear but vague. It specifies the verb 'Get' and resource 'Synapse entity', but doesn't explain what a Synapse entity is or distinguish it from sibling tools like 'get_entity_children' or 'get_entity_annotations'. The purpose is understandable but lacks specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. With siblings like 'query_entities', 'search_entities', and 'get_entity_children', it's unclear whether this is for retrieving a single entity by exact ID versus other lookup methods. No context, exclusions, or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_entity_annotationsC

Get annotations for an entity.

ParametersJSON Schema
NameRequiredDescriptionDefault
entity_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Get annotations' but doesn't clarify if this is a read-only operation, what permissions might be required, how the annotations are formatted, or if there are rate limits. The description is too minimal to provide meaningful behavioral context beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, straightforward sentence with no wasted words. It's front-loaded and efficiently conveys the core action, though it could be more informative without sacrificing brevity. The structure is clear but minimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (which likely defines the return values), the description doesn't need to explain outputs. However, with 1 parameter, 0% schema coverage, and no annotations, the description is too sparse—it doesn't provide enough context about the entity or annotations to be fully helpful. It's minimally adequate but leaves significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema provides no parameter descriptions. The description doesn't add any meaning to the 'entity_id' parameter beyond what's implied by the tool name. It doesn't explain what an entity ID is, its format, or where to obtain it, failing to compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the action ('Get') and target ('annotations for an entity'), which is clear but vague. It doesn't specify what type of annotations or what an 'entity' refers to in this context. While it distinguishes from siblings like 'get_entity' or 'query_entities', it lacks specificity about the resource being retrieved.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing a valid entity ID, or differentiate from siblings like 'get_entity' (which might retrieve entity metadata) or 'query_entities' (which might search for entities). There's no explicit when/when-not or alternative tool recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_entity_childrenB

Get child entities of a container entity.

ParametersJSON Schema
NameRequiredDescriptionDefault
entity_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Get') but does not reveal whether this is a read-only operation, if it requires specific permissions, what the output format is, or any rate limits. This leaves significant gaps for an agent to understand the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no wasted words. It is appropriately sized and front-loaded, efficiently conveying the core purpose without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (1 parameter) and the presence of an output schema, the description is minimally adequate. However, with no annotations and sibling tools present, it lacks context on usage and behavioral traits, making it incomplete for optimal agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 1 parameter with 0% description coverage, so the description must compensate. It clarifies that 'entity_id' refers to a 'container entity', adding meaning beyond the schema's minimal 'Entity Id' title. This is sufficient for the single parameter, though it could be more detailed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the verb ('Get') and resource ('child entities of a container entity'), which clarifies the basic purpose. However, it does not distinguish this tool from sibling tools like 'get_entity' or 'query_entities', leaving ambiguity about when to use this specific tool versus others for retrieving entity-related data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. With sibling tools such as 'get_entity', 'query_entities', and 'search_entities' available, there is no indication of context, prerequisites, or exclusions to help an agent choose appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_entitiesD

Query entities based on various criteria.

ParametersJSON Schema
NameRequiredDescriptionDefault
annotationsNo
entity_typeNo
nameNo
parent_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

D1.7/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. However, it offers no information about what the tool does beyond 'query'—such as whether it's read-only, destructive, requires authentication, has rate limits, or what the output looks like. This is inadequate for a tool with 4 parameters and no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—a single sentence with no wasted words. It's front-loaded and to the point, though this brevity comes at the cost of clarity and completeness. Every word earns its place, but the place is insufficient for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 parameters, 0% schema coverage, no annotations, and multiple sibling tools), the description is severely incomplete. It doesn't explain what 'entities' are, how querying works, what the parameters do, or how this differs from similar tools. While an output schema exists, the description provides no context to interpret it, making it inadequate for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning none of the 4 parameters (annotations, entity_type, name, parent_id) are documented in the schema. The description adds no semantic information about these parameters—it doesn't explain what they mean, how they're used, or what values are acceptable. This fails to compensate for the complete lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Query entities based on various criteria' is vague and tautological. It restates the tool name 'query_entities' without specifying what 'entities' are, what 'query' means operationally, or what 'various criteria' entail. It doesn't distinguish this tool from siblings like 'search_entities' or 'get_entity', leaving the purpose ambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There are no usage guidelines provided. The description doesn't indicate when to use this tool versus alternatives like 'search_entities' or 'get_entity', nor does it mention any prerequisites, context, or exclusions. This leaves the agent with no guidance on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_tableC

Query a Synapse table.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
table_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.4/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but offers no behavioral details. It doesn't disclose if this is a read-only operation, requires authentication, has rate limits, affects data, or what the response entails (e.g., format, pagination). This leaves critical behavioral traits unknown.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words, making it appropriately sized and front-loaded. It directly states the tool's function without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (querying a database table), no annotations, 0% schema coverage, and an output schema (which helps but isn't described), the description is incomplete. It lacks essential context such as query language, permissions, or behavioral traits, making it inadequate for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate but adds no parameter semantics. It doesn't explain what 'query' and 'table_id' represent (e.g., query syntax, table identifier format), leaving both parameters undocumented beyond their titles in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Query a Synapse table' states the action (query) and resource (Synapse table), which provides a basic purpose. However, it's vague about what 'query' entails (e.g., SQL-like queries, filtering, aggregation) and doesn't distinguish it from sibling tools like 'query_entities' or 'search_entities', leaving ambiguity in scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as 'query_entities' or 'search_entities'. The description lacks context about prerequisites, typical use cases, or exclusions, offering no help in tool selection among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_entitiesC

Search for Synapse entities.

ParametersJSON Schema
NameRequiredDescriptionDefault
entity_typeNo
parent_idNo
search_termYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action ('Search') without detailing permissions, rate limits, pagination, or what constitutes a 'Synapse entity'. This leaves significant gaps in understanding the tool's behavior and constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words. It is appropriately sized and front-loaded, making it easy to parse quickly, though this conciseness comes at the cost of detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, 0% schema coverage, no annotations) and the presence of an output schema, the description is incomplete. It lacks essential context such as parameter meanings, usage scenarios, and behavioral traits, making it inadequate for effective tool selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema provides no parameter details. The description adds no information about parameters like 'entity_type', 'parent_id', or 'search_term', failing to compensate for the lack of schema documentation. This leaves all three parameters semantically unclear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Search for Synapse entities' clearly states the verb ('Search') and resource ('Synapse entities'), providing a basic purpose. However, it lacks specificity about what 'Synapse entities' are and doesn't differentiate from sibling tools like 'query_entities' or 'get_entity', making it vague in context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as 'query_entities' or 'get_entity'. There is no mention of context, exclusions, or prerequisites, leaving the agent with no usage direction beyond the basic action.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv1.0.0
    • First observedget_datasets_as_croissant
    • First observedget_entity
    • First observedget_entity_annotations
    • First observedget_entity_children
    • First observedquery_entities
    • First observedquery_table
    • First observedsearch_entities
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.9/5.0

Scored across 7 tools

Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers