You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The [Synapse MCP server](https://github.com/Sage-Bionetworks/synapse-mcp) implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) and lets AI assistants (Claude, GitHub Copilot, Cursor, and others) directly query Synapse — search for datasets, inspect entity metadata, explore project hierarchies, and trace provenance — without you writing any code.
4
+
5
+
The server is implemented in Python and built on top of this `synapseclient` package, so its behavior and capabilities mirror what you can do programmatically through the Python client.
6
+
7
+
!!! warning "Terms of Service"
8
+
Using the Synapse MCP server with consumer AI services that store conversation data may violate the Synapse Terms of Service prohibition on data redistribution. Prefer enterprise deployments with data-residency guarantees or self-hosted models when working with sensitive or restricted datasets.
9
+
10
+
---
11
+
12
+
## Installation
13
+
14
+
### Remote server (recommended)
15
+
16
+
The hosted MCP server at `https://mcp.synapse.org/mcp` authenticates via OAuth2 — no token management required.
17
+
18
+
#### "Claude Code (CLI)"
19
+
20
+
```bash
21
+
claude mcp add --transport http synapse -- https://mcp.synapse.org/mcp
22
+
```
23
+
24
+
On first use, Claude Code will open a browser window to complete the OAuth2 login.
25
+
26
+
#### "Claude Desktop"
27
+
28
+
1. Open **Settings → Connectors → Add custom connector**
29
+
2. Enter the URL: `https://mcp.synapse.org/mcp`
30
+
3. Save and restart Claude Desktop
31
+
32
+
#### "VS Code / GitHub Copilot"
33
+
34
+
Add to your `settings.json` or `.vscode/mcp.json`:
35
+
36
+
```json
37
+
{
38
+
"mcp": {
39
+
"servers": {
40
+
"synapse": {
41
+
"type": "http",
42
+
"url": "https://mcp.synapse.org/mcp"
43
+
}
44
+
}
45
+
}
46
+
}
47
+
```
48
+
49
+
### Local installation
50
+
51
+
For air-gapped environments or development, you can run the server locally using a [Personal Access Token (PAT)](https://www.synapse.org/#!PersonalAccessTokens:0).
Configure your MCP client to point to `http://localhost:8000/mcp` (or the port shown in the startup output).
62
+
63
+
---
64
+
65
+
## Available tools
66
+
67
+
For the full and up-to-date list of tools, see the [synapse-mcp repository](https://github.com/Sage-Bionetworks/synapse-mcp). At the time of writing, the server exposes tools including:
68
+
69
+
-`search_synapse` — full-text search across public and private entities
70
+
-`get_entity` — fetch core metadata for any entity by Synapse ID
-`get_entity_children` — list children within a project or folder
73
+
-`get_entity_provenance` — inspect the activity log and inputs/outputs for an entity version
74
+
75
+
---
76
+
77
+
## Example prompts
78
+
79
+
Once the MCP server is connected, you can interact with Synapse in natural language. Here are some useful prompts to try:
80
+
81
+
**Discover data**
82
+
83
+
```
84
+
Search Synapse for RNA-seq datasets related to Alzheimer's Disease.
85
+
```
86
+
87
+
```
88
+
What files are in the project syn12345678?
89
+
```
90
+
91
+
**Inspect metadata**
92
+
93
+
```
94
+
What are the annotations on syn9876543?
95
+
```
96
+
97
+
```
98
+
Show me the provenance for the latest version of syn11223344.
99
+
```
100
+
101
+
**Explore a project**
102
+
103
+
```
104
+
List all folders and files in syn5678901 and summarize what the project contains.
105
+
```
106
+
107
+
**Combine with code generation**
108
+
109
+
```
110
+
Find the Synapse ID for the ROSMAP bulk RNA-seq dataset, then write Python code
111
+
using synapseclient to download it and load it into a pandas DataFrame.
112
+
```
113
+
114
+
---
115
+
116
+
## Feature requests and feedback
117
+
118
+
Have an idea for a new MCP tool or want to report a bug? [Open a support ticket](https://sagebionetworks.jira.com/servicedesk/customer/portal/9/group/16/create/206) via the Sage Bionetworks service desk.
Copy file name to clipboardExpand all lines: docs/index.md
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,6 +28,10 @@ Installing this package will install `synapseclient`, `synapseutils` and the com
28
28
*[Further Reading](./explanations/home.md) to gain a deeper understanding of best practices and advanced use cases
29
29
* Our [release notes](./news.md)
30
30
31
+
## Use Synapse with AI assistants
32
+
33
+
The [Synapse MCP server](./guides/synapse_mcp.md) lets you query Synapse directly from AI tools like Claude, GitHub Copilot, and Cursor using natural language — search datasets, inspect metadata, explore project hierarchies, and generate `synapseclient` code, all without leaving your AI assistant. See the [how-to guide](./guides/synapse_mcp.md) to get started in minutes.
34
+
31
35
## Additional Background
32
36
33
37
* Read [about Synapse](https://help.synapse.org/docs/About-Synapse.2058846607.html)—how it got started and how it fits into the bigger data-sharing picture
Provenance is a concept describing the origin of something. In Synapse, it is used to describe the connections between the workflow steps used to create a particular file or set of results. Data analysis often involves multiple steps to go from a raw data file to a finished analysis. Synapse’s provenance tools allow users to keep track of each step involved in an analysis and share those steps with other users.
3
+
Provenance is a concept describing the origin of something. In Synapse, it is used to describe the connections between the workflow steps used to create a particular file or set of results. Data analysis often involves multiple steps to go from a raw data file to a finished analysis. Synapse's provenance tools allow users to keep track of each step involved in an analysis and share those steps with other users.
7
4
8
5
The model Synapse uses for provenance is based on the [W3C provenance spec](https://www.w3.org/TR/prov-n/) where items are derived from an activity which has components that were **used** and components that were **executed**. Think of the **used** items as input files and **executed** items as software or code. Both **used** and **executed** items can reside in Synapse or in URLs such as a link to a GitHub commit or a link to a specific version of a software tool.
9
6
10
-
[Dive into Activity/Provenance further here](../../explanations/domain_models_of_synapse.md#activityprovenance)
11
7
12
8
## Tutorial Purpose
13
9
In this tutorial you will:
@@ -18,4 +14,108 @@ In this tutorial you will:
18
14
1. Delete an activity
19
15
20
16
## Prerequisites
21
-
- In order to follow this tutorial you will need to have a [Project](./project.md) created with at least one [File](./file.md) with multiple [Versions](./versions.md).
17
+
- In order to follow this tutorial you will need to have a [Project](./project.md) created with a Folder named `biospecimen_experiment_1` containing at least one [File](./file.md). You will also need the Synapse ID of that file (e.g. `synNNNNN`).
18
+
19
+
## 1. Add a new Activity to your File
20
+
21
+
#### First retrieve the project, folder and a file is created within that folder to track provenance
An `Activity` captures what was **used** (input data and reference URLs) and **executed** (code and software) to produce a file. Here we record a QC pipeline run on the biospecimen data:
<summary>You'll notice the output looks like:</summary>
37
+
38
+
```
39
+
Stored file: fileA.txt (version 1) with activity: Quality Control Analysis
40
+
```
41
+
</details>
42
+
43
+
44
+
## 2. Add a new Activity to a specific version of your File
45
+
46
+
Each time you store an updated file, Synapse creates a new version. You can associate a distinct activity with each version to capture the full history of how the data evolved. Here we record a downstream analysis step that used the QC-passed data from version 1:
<summary>You'll notice the output looks like:</summary>
54
+
55
+
```
56
+
Stored activity 'Downstream Analysis' on file fileA.txt (version 2)
57
+
```
58
+
</details>
59
+
60
+
61
+
## 3. Print stored activities on your File
62
+
63
+
Use `Activity.from_parent()` to retrieve the provenance for any version of a file. Pass a `parent_version_number` to retrieve the activity for a specific older version:
Description: Initial QC analysis of biospecimen data using the FastQC pipeline.
83
+
```
84
+
</details>
85
+
86
+
87
+
## 4. Delete an activity
88
+
89
+
Deleting an activity is a two-step process: first call `disassociate_from_entity()` to remove the link between the activity and the file version, then call `delete()` to remove the activity record from Synapse entirely:
0 commit comments