get_entity
Retrieve Synapse entities like datasets, projects, folders, files, or tables by their unique ID to access metadata and annotations programmatically.
Instructions
Get a Synapse entity by ID.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/synapse_mcp/tools.py:44-55 (handler)Executes the core logic of the get_entity tool: input validation, retrieves entity operations from context state, and calls get_entity_by_id on the base operations.
def get_entity(entity_id: str, ctx: Context) -> Dict[str, Any]: """Return Synapse entity metadata by ID (projects, folders, files, tables, etc.).""" if not validate_synapse_id(entity_id): return {"error": f"Invalid Synapse ID: {entity_id}"} try: entity_ops = get_entity_operations(ctx) return entity_ops["base"].get_entity_by_id(entity_id) except ConnectionAuthError as exc: return {"error": f"Authentication required: {exc}", "entity_id": entity_id} except Exception as exc: # pragma: no cover - defensive path return {"error": str(exc), "entity_id": entity_id} - src/synapse_mcp/tools.py:34-43 (registration)The @mcp.tool decorator registers the 'get_entity' function as an MCP tool, defining its title, description, and operational hints.
@mcp.tool( title="Fetch Entity", description="Return Synapse entity metadata by ID (projects, folders, files, tables, etc.). Only retrieves metadata information - does not download file content.", annotations={ "readOnlyHint": True, "idempotentHint": True, "destructiveHint": False, "openWorldHint": True, }, ) - Implements the low-level retrieval of Synapse entity metadata using the Synapse client, called by the tool handler.
def get_entity_by_id(self, entity_id: str) -> Dict[str, Any]: """Get an entity by ID. Args: entity_id: The Synapse ID of the entity Returns: The entity as a dictionary """ # IMPORTANT: Always keep downloadFile=False to avoid downloading file content # when fetching entity metadata. This prevents unnecessary downloads and # keeps the operation lightweight for metadata-only operations. entity = self.synapse_client.get(entity_id, downloadFile=False) return self.format_entity(entity) - Factory function that retrieves or lazily initializes per-connection entity operations (including base operations) from the MCP context state.
def get_entity_operations(ctx: Context) -> Dict[str, Any]: """Get entity operations for this connection's synapseclient.""" synapse_client = get_synapse_client(ctx) entity_ops = ctx.get_state("entity_ops") if entity_ops: return entity_ops entity_ops = { "base": BaseEntityOperations(synapse_client), "project": ProjectOperations(synapse_client), "folder": FolderOperations(synapse_client), "file": FileOperations(synapse_client), "table": TableOperations(synapse_client), "dataset": DatasetOperations(synapse_client), } ctx.set_state("entity_ops", entity_ops) return entity_ops