MCP Server

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI applications connect to external data sources and tools through a unified interface. Pria speaks MCP in both directions — see below.

The Two MCP Roles in Pria

Pria participates in the MCP ecosystem in two distinct ways. Most administrators will use one or both; understanding the distinction up front saves a lot of confusion.

Pria AS an MCP server

Your IDE, agent, or other LLM application connects to Pria as an MCP server. Pria exposes tools like search-instance-rag and api-rt-docs so external assistants can query your Digital Twin’s knowledge base and API.

Pria CONSUMING MCP servers

Your Digital Twin calls out to external MCP servers (Slack, Zapier, a custom internal MCP server) as tools during a conversation. The external MCP server becomes part of the Twin’s toolkit.

The rest of this page walks through both, with quick‑start recipes and links to the deeper docs.

What Pria Exposes as an MCP Server

Search Your Knowledge

Query your Digital Twin’s document collection using natural‑language search via the search-instance-rag tool.

Explore the API

Access live OpenAPI documentation for both Runtime and Admin endpoints directly from your LLM.

Link Digital Twins

Connect multiple Digital Twins so one can query another’s knowledge base without duplicating data.

Quick Start — Pria AS an MCP Server

Follow these steps to expose your Digital Twin as an MCP server and connect an external client (Claude Desktop, Cursor, your own application).

Step 1 — Enable MCP on Your Digital Twin

Open your Digital Twin’s Configuration and Integrations tab, tick MCP Server Enabled, then save.

Step 2 — Copy Your MCP Server Secret

In the same place, copy the MCP Server Secret. This token authenticates clients connecting to your MCP server.

The MCP Server Secret is the only credential the MCP endpoint accepts. The Digital Twin’s Public ID is not a credential — it is public by design and will not authenticate an MCP client. Treat it like a password.

Step 3 — Configure Your MCP Client

Use the following settings in any MCP-compatible client:

Setting	Value
Server URL	`https://pria.praxislxp.com/api/mcp`
Server Label	`pria-mcp`
Authorization	`Bearer <your-mcp-server-secret>`

Description / System Instruction (optional but recommended):

Use this tool to run authoritative semantic search against the remote Digital Twin via the MCP server. Invoke search-instance-rag whenever the user's question targets content stored in the Digital Twin (prefer it over local search for remote-scope queries). Input is a natural-language query string; output is a relevance-ordered list of matches containing each item's file title, a concise summary, and a direct URL (include source_id and score when available). If no relevant results exist, return an empty list. Do not infer, synthesize, or modify content — return only what the remote Digital Twin provides.

The description tells the AI when and how to use the MCP tools. Customize it to match your use case.

Available Tools

Once connected, your MCP client can invoke these tools:

Tool	Description
`search-instance-rag`	Semantic search across your Digital Twin’s uploaded documents and knowledge base
`api-admin-docs`	Returns the Admin API OpenAPI specification for the Praxis AI Middleware
`api-rt-docs`	Returns the Runtime API OpenAPI specification for the Praxis AI Middleware

Additional tools may be available depending on your Digital Twin’s configuration and enabled connectors.

Testing Your MCP Server

Use the MCP Inspector (documentation) to validate your connection, browse available tools, and send test requests.

npx @modelcontextprotocol/inspector

Connect to https://pria.praxislxp.com/api/mcp with your Bearer token and verify that the tools listed above appear.

Protocol Version & Tool Catalog

Pria’s MCP server runs over plain HTTP at /api/mcp, built on the official MCP TypeScript SDK (@modelcontextprotocol/sdk). It keeps no session state between calls, and it agrees the protocol version with each client automatically — so you do not have to configure a version anywhere. The currently exposed tools are:

Tool	Input	Purpose
`search-instance-rag`	`message` (string), optional `assistantId`	Semantic RAG search over the Twin’s documents; optionally scoped to one assistant’s collections
`api-rt-docs`	`asYaml` (boolean)	The Runtime API OpenAPI spec, as JSON or YAML
`api-admin-docs`	`asYaml` (boolean)	The Admin API OpenAPI spec, as JSON or YAML

Additional tools may be added over time. Use the Inspector’s tools/list to see the current catalog for your deployment.

Pria CONSUMING an External MCP Server

In the other direction, your Digital Twin can call out to any external MCP‑compatible server during a conversation. Once configured, the external server’s tools appear in the Twin’s toolkit alongside Pria’s built‑in tools — the model can decide to invoke them when relevant. Common reasons to add an external MCP server:

A company knowledge base running its own MCP server (Notion, internal docs MCP).
A task / automation hub like Slack, Zapier, or a workflow engine.
A custom domain MCP server you built — for example, a server that exposes your CRM, your ticketing system, or a proprietary scientific database.
A second Praxis Digital Twin (see Linking Digital Twins below).

Where to Wire It Up

External MCP servers are configured per Digital Twin, on the Connector MCP and Tools tab of the Digital Twin editor:

Add a connector

Enter its Name (Label), Server URL and, if the server needs one, an Authorization Header.

Test it

Select Test connection. Pria asks the server for its tool list with the values in the form, before anything is saved, and says what went wrong if it can’t reach it.

Pick the tools

Switch Tools on and tick the tools to allow under Tools Choice. With Require Approval on, the person in the conversation approves each call, except the tools you tick under Ignore Approval for Tools.

Once active, the server’s tools are available to every assistant and every user of that Digital Twin, on every conversation model that supports tools — no per-user setup. Servers are deliberately scoped to a single Twin (this keeps credentials isolated). If several Twins need the same upstream MCP server, add it to each one. For the full field reference, tool filters, approvals, and troubleshooting, see MCP Servers (admin).

Authentication to External MCP Servers

When Pria connects out to a third‑party MCP server, you supply the credentials Pria should present:

Authorization header — most common. Paste the full header value (for example Bearer xyz123…) in the connector’s Authorization Header field.
No auth — for open public MCP servers (rare).

Pria forwards the configured credential on every tool invocation. The token never appears in any model‑visible content. Outbound tool calls also carry a verified identity for the signed-in user that partner servers can check against your MCP Signing Secret — a separate key, different from the MCP Server Secret above, that lets the far end prove a request really came from your Pria twin on behalf of a real user — see MCP Servers (admin) for what this enables, and Verified identity for how a partner server checks it.

Linking Digital Twins via Connector MCP

A common use case is connecting two Digital Twins so that Twin B can search Twin A’s knowledge base in real time — without copying or syncing documents between them. Why link twins?

Keep source knowledge centralized in one twin while others query it on demand
Updates to Twin A’s documents are instantly available to Twin B
Avoid data duplication and keep all twins consistent

How to Set It Up

Enable MCP on Twin A

Follow the Quick Start above to enable MCP and copy Twin A’s MCP Server Secret.

Add a Connector MCP in Twin B

In Twin B, open the Connector MCP and Tools tab and add a new connector:

Server URL: https://pria.praxislxp.com/api/mcp
Authorization Header: Bearer <Twin A's MCP Server Secret>

Select Test connection: search-instance-rag and the two API tools should be listed.

Connector MCP configuration pointing to Twin A

Save and Enable

Save the connector and make sure its Status is active.

Connector MCP list showing the enabled connector

Try It in a Conversation

Send a query in Twin B that targets Twin A’s knowledge. For example:

Using the pria-mcp, search for information about “onboarding process”

Testing connectivity through the connector MCP

Review Tool Details

Check the agent details to confirm the tool was invoked correctly and returned results.

Agent details showing MCP tool invocation

The bearer value you provide in Twin B’s connector must be Twin A’s MCP Server Secret (not its Public ID). This ensures authenticated, secure communication between twins.

MCP in Real-Time Voice Conversations

MCP tools are also available during Convo Mode — your Digital Twin can invoke MCP tools during live voice conversations, for example searching a connected twin’s knowledge base while speaking with a user. Every voice provider can reach your connectors — what differs is how, and how a tool that needs approval is asked for.

Provider	How MCP reaches it	When a tool needs approval
OpenAI Realtime	OpenAI’s own native connector	An approval card appears in your browser
xAI Realtime, Gemini Live	Pria acts as the MCP client and offers the connector’s tools as ordinary tools, with its signed identity	The microphone pauses and a card appears; the twin can’t ask out loud, so watch for it — you have 45 seconds
Anam, Cartesia, OpenAI GPT-Live	Each spoken turn is answered by the twin’s own model, so connectors work as in typed chat	Anam and Cartesia say out loud that they need permission; the card appears in the live transcript (GPT-Live shows the card only)
ElevenLabs	The same as typed chat	Not available: the twin says so and asks you to try again from the Pria chat. Tools that need no approval work normally

A twin’s voice turns may run on a different model than its typed turns (the Anam Response Model setting, or an assistant’s STS / Voice Conversation Model). Connectors follow the model the turn actually runs on.

See Convo Mode for the provider comparison.

Shared MCP Configuration for a Digital Twin

Administrators configure external MCP servers once per Digital Twin on the Connector MCP and Tools tab in the Admin dashboard. This makes the server’s tools available to all users of that Digital Twin without any individual setup. See MCP Servers (admin) for the field reference, and Configuration for the inbound MCP Server switch, Secret, and identity-signing settings.

Troubleshooting

Symptom	Solution
”Unauthorized: MCP Secret is invalid” (or 401)	Verify your `Authorization: Bearer <token>` header carries the Digital Twin’s MCP Server Secret exactly. The Twin’s Public ID is not accepted as a credential. Invalid-secret errors are returned inside the tool result, so check the tool output text, not just the HTTP status.
”MCP Server is disabled for this instance”	MCP Server Enabled is off — tick it and save on Configuration and Integrations.
Connection refused	Confirm the server URL is `https://pria.praxislxp.com/api/mcp` and your network allows outbound HTTPS.
Tools not appearing	Ensure MCP Server Enabled is on and saved. For a connector in your own twin, select Test connection in its editor to see what the server answers.
Twin B ignores the connector	Check that the server label and tool names are correct. Try an explicit prompt: “Using the pria-mcp, execute search-instance-rag to find information on ‘xyz‘“
Unexpected results	Use the MCP Inspector to send the same query directly and compare responses.

Learn More

Model Context Protocol specification — The official MCP documentation and standard

MCP Servers (admin) — Digital-Twin-level MCP server configuration
Configuration — Where the MCP Server switch and Secret live
Connectors — Adding external MCP servers as Twin‑scoped connectors
Tools — Tool definitions available to your Digital Twin
Convo Mode — Voice conversations with MCP tool support
API Reference — Runtime and Admin REST APIs that the MCP server mirrors
API Keys — Personal API keys for programmatic access to Pria

Overview

Getting Started

LMS Integrations

Voice & Avatars

Web & Chat Integrations

JavaScript SDK

Authentication

REST API

Runtime API

Administrator API

MCP Server

What is MCP?

The Two MCP Roles in Pria

Pria AS an MCP server