Skip to main content
Glama
enesjakozh
susheel

Synapse MCP Server

by susheel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Synapse MCP 服务器

模型上下文协议 (MCP) 服务器，公开 Synapse 实体（数据集、项目、文件夹、文件、表）及其注释并支持 OAuth2 身份验证。

概述

此服务器提供 RESTful API，用于通过模型上下文协议 (MCP) 访问 Synapse 实体及其注释。它允许您：

  • 使用 Synapse 进行身份验证

  • 通过 ID 检索实体

  • 按名称检索实体

  • 获取实体注释

  • 获取实体子项

  • 根据各种条件查询实体

  • 查询 Synapse 表

  • 获取 Croissant 元数据格式的数据集

Related MCP server: Reactome MCP Server

安装

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

从 PyPI 安装

# Install from PyPI
pip install synapse-mcp

用法

启动服务器

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

这将在默认端口（9000）上启动 MCP 服务器。

使用 CLI

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

命令行选项

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)

运行测试

# Run all tests with coverage
./run_tests.sh

# Or run pytest directly
python -m pytest

测试服务器

python examples/client_example.py

身份验证方法

环境变量

服务器支持以下环境变量：

  • HOST ：要绑定的主机（默认值：127.0.0.1）

  • PORT ：监听的端口（默认值：9000）

  • MCP_TRANSPORT ：要使用的传输协议（默认值：stdio）

    • stdio ：使用标准输入/输出进行本地开发

    • sse ：使用服务器发送事件进行云部署

  • MCP_SERVER_URL ：服务器的公共 URL（默认值：mcp://127.0.0.1:9000）

    • 用于 OAuth2 重定向和服务器信息

服务器支持两种认证方式：

  1. Auth Token ：使用 Synapse 身份验证令牌进行身份验证

  2. OAuth2 ：使用 Synapse 的 OAuth2 服务器进行身份验证

API 端点

服务器信息

  • GET /info获取服务器信息

工具

  • GET /tools - 列出可用工具

  • POST /tools/authenticate - 使用 Synapse 进行身份验证

  • POST /tools/get_oauth_url - 获取 OAuth2 授权 URL

  • POST /tools/get_entity - 通过 ID 或名称获取实体

  • POST /tools/get_entity_annotations - 获取实体的注释

  • POST /tools/get_entity_children - 获取容器实体的子实体

  • POST /tools/query_entities - 根据各种条件查询实体

  • POST /tools/query_table - 查询 Synapse 表

资源

  • GET /resources - 列出可用资源

  • GET /resources/entity/{id} - 通过 ID 获取实体

  • GET /resources/entity/{id}/annotations - 获取实体注释

  • GET /resources/entity/{id}/children - 获取实体子项

  • GET /resources/query/entities/{entity_type} - 按类型查询实体

  • GET /resources/query/entities/parent/{parent_id} - 通过父 ID 查询实体

  • GET /resources/query/entities/name/{name} - 按名称查询实体

  • GET /resources/query/table/{id}/{query} - 使用类似 SQL 的语法查询表

OAuth2 端点

  • GET /oauth/login - 重定向到 Synapse OAuth2 登录页面

  • GET /oauth/callback - 处理来自 Synapse 的 OAuth2 回调

示例

验证

您需要使用真实的 Synapse 凭据进行身份验证才能使用服务器：

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 身份验证

1. 重定向流程（基于浏览器）

将用户定向到 OAuth 登录 URL：

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

2. 基于 API 的流程

对于程序化使用，首先获取授权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

获取实体

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)

获取实体注释

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)

查询实体

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)

查询表

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)

获取 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)

部署

Docker

您可以使用 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

部署到 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

与 Claude Desktop 集成

您可以将此 Synapse MCP 服务器与 Claude Desktop 集成，以使 Claude 能够在您的对话中直接访问和使用 Synapse 数据。

设置说明

  1. 首先，克隆存储库并安装要求：

# 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. 配置 Claude Desktop 以使用 Synapse MCP 服务器：

    • 打开 Claude 桌面

    • 点击 Claude 菜单并选择“设置...”

    • 点击左侧栏中的“开发者”

    • 点击“编辑配置”

    • 将以下配置添加到mcpServers部分：

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

  1. 保存配置文件并重新启动Claude Desktop

  2. 您现在可以在与 Claude 的对话中使用 Synapse 数据。例如：

    • “从 Synapse 获取 ID 为 syn123456 的实体”

    • “查询Synapse项目syn123456中的所有文件”

    • “获取 Synapse 实体 syn123456 的注释”

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

执照

麻省理工学院

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