> For the complete documentation index, see [llms.txt](https://shoppad.gitbook.io/yedric/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shoppad.gitbook.io/yedric/developers/mcp-server.md). # MCP Server Yedric exposes a hosted [MCP](https://modelcontextprotocol.io) server, so you can manage your assistants and read your conversation data from any MCP client, such as Claude Desktop, Claude Code, Cursor, or ChatGPT. The MCP server lives at: ``` https://app.yedric.ai/mcp ``` ## Connecting Add the URL above as a remote (HTTP) MCP server in your client. The first time your client connects, Yedric walks you through a standard OAuth sign-in. Your client then receives a token and stays connected. The token is scoped to the organization you chose, so tools only ever see that organization's assistants and conversations. You can grant access to a different organization by reconnecting and choosing another one. Clients that support MCP's Dynamic Client Registration (Claude Desktop, Claude Code, and others) register themselves automatically, so there is nothing to configure beyond the URL. ## Available tools Once connected, the following tools are available (subject to the permissions you granted). Every parameter is listed. Anything not marked optional is required. ### Assistants | Tool | Parameters | What it does | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_assistants` | none | Every assistant in the organization. | | `search_assistants` | `query` | Find assistants by a substring of the name. | | `get_assistant` | `assistantId` | Full detail for one assistant: prompt, model, first message, selected tool servers, knowledge base documents, and a `liveChat` block with the live chat settings (see below). | | `update_assistant_prompt` | `assistantId`, `systemPrompt` | Replace the assistant's instructions outright. | | `update_assistant` | `assistantId`, plus any of `name`, `modelId`, `firstMessage`, `knowledgeBaseEnabled`, `toolServerIds`, `supportEmail`, `liveChatAutoAssign`, `liveChatMaxChatsPerAgent`, `liveChatIdleTimeoutMinutes`, `liveChatAssignedUserIds`, `liveChatSchedule` | Update one or more fields. Every field except `assistantId` is optional, so send only what you are changing. `toolServerIds` is an array and replaces the current selection. The `liveChat*` fields and `supportEmail` are described below. | | `add_knowledge_base_document` | `assistantId`, `title`, `content` | Add a plain-text document to the knowledge base. Chunking and embedding happen in the background, so the document is not searchable the instant this returns. | | `pull_agent_config` | `assistantId` | The assistant's full configuration, for diffing or version control. | #### Live chat settings The settings on the assistant's **Live chat & support** card are readable and writable over MCP, so a connected tool can set business hours or staffing without opening the dashboard. See [Live Chat](/yedric/going-further/live-chat.md) for what each setting does. `get_assistant` returns them grouped in a `liveChat` block. Every key is always present, with `null` meaning "not set", so you can tell "no cap" from "did not look": ```json "liveChat": { "supportEmail": "support@example.com", "autoAssign": true, "maxChatsPerAgent": 2, "idleTimeoutMinutes": 15, "assignedUserIds": [], "schedule": { "timezone": "America/Los_Angeles", "week": [[], [{ "open": "09:00", "close": "17:00" }], [{ "open": "09:00", "close": "17:00" }], [{ "open": "09:00", "close": "17:00" }], [{ "open": "09:00", "close": "17:00" }], [{ "open": "09:00", "close": "17:00" }], []] } } ``` `update_assistant` takes the same settings as flat, individually optional fields: | Field | Value | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `supportEmail` | The address that receives live chat transcripts and offline-form messages. An empty string falls back to the organization default. | | `liveChatAutoAssign` | `true` to hand incoming chats to the least-loaded available agent automatically. | | `liveChatMaxChatsPerAgent` | How many concurrent live chats one agent can hold. `0` or `null` means unlimited. | | `liveChatIdleTimeoutMinutes` | Minutes of silence before an active chat ends itself. `0` or `null` means no timeout. | | `liveChatAssignedUserIds` | Dashboard user ids allowed to staff this assistant. An empty array means any available agent. | | `liveChatSchedule` | Weekly business hours, or `null` to turn business hours off. `timezone` is an IANA zone name. `week` is exactly seven entries, index 0 being Sunday, each a list of `{ "open", "close" }` intervals in `HH:MM`. `open` is inclusive, `close` is exclusive and must be later than `open`, and `"24:00"` means end of day. An empty list means closed that day. | A schedule is validated the same way the dashboard validates it, so an unknown timezone or an interval that closes before it opens is rejected with the reason rather than saved. ### Widget | Tool | Parameters | What it does | | ---------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_widget_config` | `assistantId` | The assistant's current widget appearance. | | `update_widget_config` | `assistantId`, `appearance` | Patch the widget appearance. `appearance` is a partial object and its keys must match the widget configuration schema, so read the current config first and change what you need. | ### Conversations | Tool | Parameters | What it does | | -------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_conversations` | all optional: `assistantId`, `limit`, `cursor`, `startDate`, `endDate`, `sentiment`, `tag` | Conversation sessions, newest first. `limit` is 1 to 200. `startDate` and `endDate` are epoch milliseconds and are inclusive bounds on last activity. `sentiment` is one of `positive`, `neutral`, `negative`. `tag` matches a system or custom tag. Pass the `nextCursor` from a previous response as `cursor` to page; omit it for the first page. | | `get_conversation` | `sessionId` | The full message transcript for one session. | ### Trends | Tool | Parameters | What it does | | ------------ | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_trends` | `assistantId`, optional `startDate`, `endDate` | Aggregated trends: volume, sentiment, request types, top topics, feature requests, pain points, and token usage. Dates here are ISO `YYYY-MM-DD` strings, not epoch milliseconds. Defaults to the last 60 days. | {% hint style="warning" %} The date parameters are not consistent between these two tools. `list_conversations` takes epoch milliseconds; `get_trends` takes `YYYY-MM-DD` strings. Passing one format where the other is expected is the most common mistake here. {% endhint %} ### Simulations | Tool | Parameters | What it does | | ------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `list_simulations` | `assistantId` | The assistant's saved simulations. | | `list_simulation_suites` | `assistantId` | The assistant's simulation suites. | | `run_simulation` | `simulationId`, optional `numberOfRuns` | Run one simulation. `numberOfRuns` is a positive integer. | | `run_simulation_suite` | `suiteId`, optional `pinnedAgentVersionId` | Run a whole suite, optionally against a specific saved version of the assistant. | | `list_suite_runs` | `suiteId` | Past runs of a suite. | | `get_suite_run` | `suiteRunId` | One suite run. | | `get_agent_test_job` | `jobId`, optional `includeTranscripts`, `includeConfig`, `failedOnly`, `runIndex` | Results for a run. The optional flags exist to keep responses manageable: `failedOnly` returns just the runs that errored, halted, or failed a criterion, and within those only the failing criteria. `includeTranscripts` is expensive, so pair it with `runIndex` to fetch one run at a time. `includeConfig` returns the simulation definition that was actually run. | See [Simulations](/yedric/going-further/simulations.md) for what these concepts mean.