Skip to content

Use Desk Genie from code

Any program can reach Desk Genie characters through the hosted MCP server. The official MCP client libraries handle the protocol, and your access token is the only credential.

TypeScript

npm install @modelcontextprotocol/sdk
export DESK_GENIE_TOKEN="dg_..."

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-app", version: "1.0.0" });  // the server reports itself as desk-genie-hosted
await client.connect(new StreamableHTTPClientTransport(
  new URL("https://stage.app.deskgenie.studio/api/mcp"),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.DESK_GENIE_TOKEN}` } } },
));

const { tools } = await client.listTools();            // list_characters, talk, get_usage
const reply = await client.callTool({
  name: "talk",
  arguments: { character: "pip", message: "In one sentence, what do you help with?" },
});
console.log(reply.isError ? "Not sent:" : "Pip:", reply.content[0].text);
await client.close();

The hosted server answers every POST with one JSON response and opens no event streams, so the client needs no long-lived connection.

Other languages

Use that language's MCP client with the Streamable HTTP transport and an Authorization: Bearer header. Without a library, each call is one HTTPS POST of a JSON-RPC message; the MCP page shows a curl example.

What to handle

  • A missing, expired or revoked token returns HTTP 401. A session already open when you revoke a token ends on its next request.
  • A call that cannot finish, such as one at your daily limit, returns isError: true and a message you can show. See Limits and errors.
  • A request from a web page carries an Origin header. The server refuses any origin that is not Desk Genie's own, so call it from a server or a local program, not from a browser page.
  • talk starts a new conversation each time, and each call counts as a turn.

Browser control

A browser API to place, speak through and animate an embedded character follows in a later release. Today the website embed gives you the character with Talk and Text buttons.