Skip to main content

MCP Reference

Connect your AI assistant to your organization's knowledge — emails, meetings, Slack messages, documents, and people — through simple, natural conversation. The Digital Twin MCP Server gives developers a unified tool interface to query team knowledge without building separate integrations for each source.

Your organization's MCP URL is available in Twin Settings → Use Digital Twin Anywhere. The URL ends in /niobe/mcp.

Authentication​

The MCP server accepts two authentication methods. Prefer OAuth when your MCP client supports it.

MCP clients that support the Model Context Protocol authorization flow — for example Claude and ChatGPT — can connect with only the MCP URL. No Personal Access Token is required.

When the client first calls the MCP endpoint without a token, the server responds with an OAuth challenge. The client then:

  1. Discovers authorization-server metadata from the protected resource.
  2. Opens a browser consent page where the user signs in and approves scopes.
  3. Exchanges the authorization code (with PKCE) for an access token and refresh token.
  4. Sends the access token as a bearer token on subsequent MCP requests, refreshing as needed.

On the consent screen, the user can approve or deselect individual scopes. Disconnecting the connector in the MCP client revokes the refresh token grant.

OAuth uses Client ID Metadata Documents (CIMD) for public clients. Your organization controls which client hosts are allowed (for example claude.ai or chatgpt.com). Local / loopback redirect clients (such as CLI tools) may require an admin to enable localhost redirects for the org.

Personal Access Token (PAT)​

Clients that do not support OAuth — or scripts and custom agents that need a static credential — can authenticate with a Personal Access Token (PAT) as a bearer token in the Authorization header:

Authorization: Bearer <personal_access_token>

Create and manage PATs in Twin Settings → Use Digital Twin Anywhere. For end-user setup of a generic MCP client, see MCP Server.

OAuth scopes​

When connecting via OAuth, tool access is gated by the scopes granted at consent time (intersected with the scopes your organization enables). Relevant scopes for the tools on this page:

ScopeGrants
twins:readList and search digital twins, and find topic experts
ask:readAsk your digital twin in read-only mode
ask:writeAsk your digital twin in read+write mode (read data and perform actions on your behalf)
documents:readRead the full content of documents cited in twin responses
expertise:writeCreate and publish expertise documents on your twin

PAT-authenticated calls use the scopes assigned when the token was created; they are not subject to the OAuth consent checkbox flow.

Overview​

The Digital Twin MCP Server is built on the Model Context Protocol (MCP), an open standard for connecting AI models to external data sources. Once configured, your AI assistant can answer questions like "what did my team discuss last week?" or "who in the org knows about HIPAA compliance?" — pulling from real workplace data rather than relying on memory.

Each person in your organization has a digital twin: a continuously updated knowledge model trained on their emails, documents, meetings, and messages. You can query your own twin, a colleague's twin, or purpose-built custom twins for specific topics.

Available Tools​

In most cases, you'll use ask and search_twins together. Use save_expertise_document when the user wants to capture something as durable twin knowledge.

ToolWhat it does
askYour primary entry point. Ask anything across your workplace knowledge — emails, meetings, Slack, documents, and more. You can also query a colleague's twin or a custom twin.
search_twinsPreferred tool for twin discovery. Find a person's digital twin by name or email, or discover who in your organization has expertise on a particular topic.
get_document_contentRetrieve the full text of any document cited in an ask response. Great for going deeper on a specific source.
save_expertise_documentSave Markdown content as a published expertise document on the caller's own twin, so it becomes part of their searchable expertise.

Usage Examples​

Here are common patterns to get you started.

Example 1 — Ask about emails and meetings​

User prompt: "What did my team discuss about the Q3 roadmap in last week's meetings?"

The ask tool searches across your connected calendar, meeting transcripts, and email threads simultaneously, surfacing relevant discussions with citations so you can trace every answer back to its source.

Example 2 — Query a colleague's twin​

User prompt: "Ask Sarah's twin what her current priorities are for Q2."

Use search_twins to locate Sarah by name or email, then pass her twin ID to ask. This lets you surface context from a colleague's perspective — useful for async research before a meeting or when someone is unavailable.

Example 3 — Find an expert in your organization​

User prompt: "Who in our org knows the most about HIPAA compliance?"

search_twins accepts topic queries in addition to names. It ranks twins by relevance to the topic and returns the people most likely to have useful knowledge — perfect for routing questions to the right person without guessing.

Example 4 — Save an expertise document​

User prompt: "Save this decision write-up to my twin so the team can find it later."

Use save_expertise_document with the Markdown body. Confirm sharing intent before calling:

  • visibility: "only_me" (default) — private to the user
  • visibility: "org" — shared with the whole organization

Optionally pass a title and a short how_summary describing how the content was produced. The tool creates and publishes the document on the caller's own twin (not a colleague's or custom twin), seeds a chat thread so the user can refine it in the product, and returns a URL to open and edit it. Present that URL to the user as a clickable link.

Over OAuth, this tool requires the expertise:write scope.

Additional Notes​

Long-running queries and the 60-second timeout​

Some queries, especially in Think mode when they need deeper reasoning across many sources, can take longer than 60 seconds. To avoid client timeout limits (for example in Claude), the Digital Twin MCP Server uses an asynchronous polling pattern instead of holding one long request open.

Here is how it works:

  1. When a query is submitted, the server starts processing and keeps the call open for up to 40 seconds.
  2. During that window, it checks progress every 1 second in the background.
  3. If the answer is ready in that window, it returns inline in the same call.
  4. If it is still running, the server returns status: "processing" with a thread_id.
  5. The client calls ask again with only that thread_id (omit query, enc_id, and agent_mode), and the same cycle repeats until the result is ready.

The 40-second window is intentional: it stays safely under the ~60-second tool timeout with enough headroom to avoid errors. A query that takes two minutes would usually finish in about three tool calls, rather than timing out.

Example of a long-running query response:

{
  "status": "processing",
  "thread_id": "abc123-thread-id",
  "message": "Query is still being processed (elapsed 40s). Call ask again with this thread_id to keep checking the status."
}

When the query completes, the response includes the answer, cited sources, and a trace_id for feedback — without the status: "processing" wrapper.

Known limitations: MCP vs. Viven UI​

The MCP server is intentionally a headless knowledge surface. It exposes core query, discovery, document, and expertise tools but does not replicate every capability available in the full Viven UI. Below are the key differences to be aware of.

Agents do not run via MCP​

The Agents feature in the Viven UI lets users create, save, schedule, and share prompt templates that can call tools and run multi-step workflows. These UI-native affordances — the agent gallery, scheduling, run history, and sharing — are not available when querying via MCP. Calling ask over MCP uses the same underlying reasoning engine, but it does not trigger saved agents or their associated automation flows. Actions and Agents hooks are treated as a planned future capability for MCP, not part of the current baseline.

Streaming and rich progress events are limited​

The Viven UI receives granular streaming events as a query runs — incremental progress, intermediate reasoning steps, and richer visual feedback. Over MCP, the behavior is closer to "wait, then receive a full payload." This is a practical constraint of the MCP transport layer and is an area of active improvement.

Twin orchestration is on the client​

In the Viven UI, multi-twin coordination happens behind the scenes. When using MCP, the model or client orchestrating the session is responsible for discovering the right twin (via search_twins), then routing ask calls to the correct twin ID. This makes MCP integrations slightly more explicit but also more flexible for custom workflows.

Admin and governance features remain UI-only​

Connection management, persona and privacy rules, and privileged visibility controls are managed through the Digital Twin Admin Console and are not exposed via MCP tools. These are intentionally kept out of the headless query interface. OAuth client allowlists and enabled scopes are also admin-managed configuration, not MCP tools.