MCP Server - Experio Documentation

Overview

The MCP Server feature lets you connect external AI tools — such as Claude Desktop, Cursor, VS Code Copilot, and other MCP-compatible clients — directly to Experio. Once connected, these tools can query your organization’s knowledge graph, search documents, and generate reports through Experio’s AI assistants. Navigate to MCP Server from the user dropdown menu in the sidebar.

Getting Started

Open MCP Server page

Click your avatar in the sidebar footer, then select MCP Server from the dropdown.

Generate an API Key

Click Generate API Key. A dialog shows your key (starting with exp_mc_). Copy it immediately — the key is shown only once and cannot be retrieved later.

Copy the MCP Config

After generating a key, the page displays a JSON configuration block. Click Copy Config to copy it to your clipboard.

Paste into your AI tool

Open your AI tool’s MCP configuration file and paste the JSON. For example:

Claude Desktop: Edit claude_desktop_config.json
Cursor: Edit MCP settings in Cursor preferences
VS Code: Edit your MCP settings file

Replace <your_exp_mc_key> in the config with the API key you copied.

Start querying

Restart your AI tool. You should now see Experio’s tools available. Ask your AI tool to query Experio’s knowledge base.

MCP Configuration Format

The configuration uses the mcp-remote transport, which works with all MCP clients:

{
  "mcpServers": {
    "experio": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-server.com/mcp",
        "--header",
        "Authorization: Bearer <your_exp_mc_key>"
      ]
    }
  }
}

The mcp-remote package is installed automatically via npx. Make sure you have Node.js installed on your machine.

Available Tools

Once connected, your AI tool has access to three Experio tools:

Tool	Description
list_assistants	Discover available AI assistants and their capabilities
ask_experio	Ask a question to an Experio assistant. Queries the knowledge graph, searches documents, and generates a report.
get_file	Download a file generated by ask_experio (CSV exports, presentations, documents)

Typical Workflow

Call list_assistants to see which assistants are available
Call ask_experio with your question, assistant name, and an optional thread_id
If the response mentions a file (e.g., /results/export.csv), call get_file with the same thread_id to get a download URL

Reading the result of ask_experio

The text of the result is the assistant’s answer. When you do not pass a thread_id, the text of an answer or a question starts with [thread_id: <id>] so you can reuse the thread. A program should read the structured content of the result instead of the text. It has these fields:

Field	Meaning
`status`	`answered`, `clarification_needed` or `error`
`text`	The answer, the assistant’s question, or the error message, without the `[thread_id: ...]` prefix
`thread_id`	The thread to pass to the next `ask_experio` call and to `get_file`
`error_code`	Set only when `status` is `error` (see below)
`result`	The same text as the text content. Kept for older integrations; use `status` and `text` instead

answered: text is the answer.
clarification_needed: the assistant asked a question and is waiting for your reply. text ends with the question and the options it offers when it has some, after anything the assistant could already say. Reply by calling ask_experio again with the same thread_id, so the assistant keeps the conversation.
error: the call failed. The result is also flagged as a tool error (isError), so MCP clients show it as a failed tool call. The HTTP status is still 200, as the MCP protocol requires for tool errors. The text of an error has no [thread_id: ...] prefix: read thread_id from the structured content.

`error_code`	What happened
`assistant_not_found`	No assistant has that exact name. Names are case-sensitive: call `list_assistants`
`no_response`	The assistant finished without producing an answer
`report_failed`	The answer could not be generated, usually a temporary problem with the AI model. Try again
`graph_unavailable`	The knowledge graph could not be queried. This does not mean there is no matching data. Try again
`internal_error`	Anything else, for example the service being overloaded. `text` has the detail

A call with missing or invalid arguments is also a tool error, but it is rejected before the tool runs, so it has no structured content.

A failed call used to come back as a normal result, with the error message as its text and isError false. If your integration looks for error messages in the text, switch to status or isError.

Example Queries

Once connected, try asking your AI tool:

“Use Experio to list all departments in the organization”
“Ask Experio to export all employees as a CSV”
“Query Experio about Cloud division employees and their skills”
“Use Experio to create a PowerPoint about the organizational structure”

Managing API Keys

Viewing Keys

The MCP Server page shows all your active API keys with:

Key prefix (first 16 characters for identification)
Name (optional label you set when creating)
Created date
Last used date

The full API key is never displayed after creation. Only the prefix is shown for identification purposes.

Revoking Keys

To revoke an API key:

Click the trash icon next to the key
Confirm the revocation in the dialog

After revoking, any AI tool using that key will immediately lose access. You can generate a new key at any time.

Multiple Keys

You can generate multiple API keys — for example, one for Claude Desktop and another for Cursor. Each key can be revoked independently.

File Downloads

When Experio generates files (CSV exports, PowerPoint presentations, Word documents, PDFs), the get_file tool returns a signed download URL. These URLs:

Expire after 10 minutes
Require no additional authentication (the URL itself is the authorization)
Work in any browser or HTTP client

Privacy and Security

Per-user API keys — Each key is tied to your account. Other users cannot use your key.
Hashed storage — API keys are stored as SHA-256 hashes. Even database administrators cannot see your raw key.
Revocable — Keys can be revoked instantly from the MCP Server page.
Scoped access — MCP tools respect the same data permissions as the web interface.
Signed file URLs — Download links are cryptographically signed and time-limited.