TwymAtlas / Documentation / MCP

Connect TwymAtlas as an MCP server

TwymAtlas exposes indexed SharePoint and GitHub knowledge over the Model Context Protocol (MCP) using streamable HTTP and Bearer API key authentication.

Overview

Agents such as Cursor or Claude Desktop can call TwymAtlas tools to search your knowledge base, list synced sources, retrieve document context, and invoke live external sources (for example Atlassian or SQL Server) that you connected in TwymAtlas. Access is scoped to the API key owner and that user’s document permissions.

Prerequisites

API key

  1. Open MCP in the TwymAtlas sidebar.
  2. Select Configure (or Reconfigure to rotate).
  3. Copy the key immediately. It is displayed once and begins with tf_.

Treat the API key as a secret. Anyone with the key can query knowledge accessible to that user.

Revoking the key from the MCP page invalidates all clients using it.

Endpoint and authentication

Base URL:

http://localhost:8000/mcp

Required header on every request:

Authorization: Bearer tf_your_api_key_here

Use the same origin as the TwymAtlas UI. For remote agents, the host must be reachable from the client machine (not only localhost).

Configure Cursor

  1. Open Cursor Settings → MCP, or edit your MCP configuration file.
  2. Add a server entry with the TwymAtlas MCP URL and Authorization header.
  3. Save the configuration and refresh MCP servers until tools are listed.

Example configuration:

Configure Codex

Use the same server definition. Example:

Replace tf_your_api_key_here with the key from the TwymAtlas MCP page, then reload MCP servers.

Dated events (TwymFabric)

Chronology uses the same payload as REST. After upload, take Postgres ids from GET /api/uploads files[].id — not graph node ids — then call get_events with those values. That is the MCP equivalent of: 

GET /api/knowledge/events?document_id=11&document_id=12&document_id=13

get_events is the listed tool (enriched events + citations[]). get_timeline is a hidden call alias, not a second tool. get_facts is the same events plus factId / entityIds. get_timeline_context is workstream columns, not a duplicate events list.

Tools reference

Tool Parameters Description
search_documents query, optional caseId, entityIds, documentTypes, dateFrom, dateTo, limit Targeted evidence retrieval. Returns documents[] with documentId, controlNumber, page, textExcerpt, relevance.
list_knowledge_sources — Lists synced SharePoint sites / GitHub repos that have accessible indexed files.
list_documents optional caseId, limit, offset, documentTypes Case-wide document inventory. Paginated. Do not call read_document per file.
read_document documentId, optional pageFrom, pageTo, caseId Deep dive: verbatim page text for one document.
get_document_context documentId, optional caseId Preferred document investigation packet: entities, facts, relationships, transactions, related documents.
list_entities optional caseId, limit, offset Entity inventory for node-wise risk scoring.
get_entity entityId Canonical entity record.
get_entity_documents entityId Documents that mention the entity (evidence path).
get_entity_context entityId Full investigation packet for one entity. Main workhorse for risk / red flags.
get_graph_context focusEntityId, optional depth (default 1) One-hop (default) neighbourhood for risk propagation.
get_entity_relationships entityId Typed relationships with documentIds.
find_path fromEntityId, toEntityId, optional maxHops Shortest path, alternatives, hop count, risky links, evidence.
get_transactions optional entityId, dateFrom, dateTo Structured payment rows (amount, parties, supporting document ids).
get_events optional document_id, entity, since, until Ordered dated events (same body as REST GET /api/knowledge/events) with workstream, source type, control number, quote, and citations. get_timeline is a hidden call alias, not a second listed tool.
get_facts optional entityId, documentId Same dated events as get_events, plus factId, entityIds, quote, control number, source type, and citations.
get_timeline_context optional entityId, dateFrom, dateTo Contracts/tenders/invoices/payments/communications/compliance tracks plus documentary gaps.
get_case_context optional caseId, section, offset, limit Case-level investigation snapshot. Page with section on large cases.
get_case_statistics optional caseId Inexpensive counts and breakdowns for dashboards.
get_entity_enrichment entityId Generic screening contract. Returns NOT_CHECKED until a provider is wired.
list_live_connections — Lists live external sources (Atlassian, SQL Server, …). Only needed to answer “what is connected?” — not a prerequisite for calling a live tool.
<provider>_<source_id>__<toolName> the provider tool's own schema One entry per tool on each connected live source, e.g. atlassian_9__searchJiraIssuesUsingJql, sqlserver_11__run_query. Response includes the provider's full text, plus citation and is_error.

Recommended agent flow (indexed knowledge / investigation):

  1. get_case_statistics or get_case_context for a structured snapshot
  2. get_entity_context / get_document_context to investigate a node or file
  3. search_documents only when you need a targeted excerpt to cite
  4. read_document when you must verify verbatim page text

Recommended agent flow (live external sources such as Jira or SQL Server):

  1. Pick the matching live tool straight from the server's tool list — every connected source's tools are published there with their real names and input schemas
  2. Call it with arguments matching its schema; cite using the returned citation
  3. For Atlassian, most tools need cloudId: get it from atlassian_<source_id>__getAccessibleAtlassianResources, or pass the site hostname directly

Live tools appear only for sources you have connected, so the tool list changes as you connect or disconnect sources. Reload MCP servers in your client after connecting a new source.

Troubleshooting

Symptom Resolution
401 Unauthorized Missing, incorrect, or revoked API key. Generate a new key on the MCP page.
Empty search results Sync a connector and confirm the document is accessible to your user.
Cannot reach /mcp Verify host/port match the TwymAtlas UI; remote clients need a publicly reachable URL.
Tools not listed Refresh or restart the MCP server entry in the client after saving configuration.

TwymAtlas MCP · Streamable HTTP · Bearer authentication