The DioscHub MCP contract

Your MCP server is a standard Model Context Protocol server. DioscHub adds a small contract on top of it: one transport, a naming rule, the tool fields it reads, and the response shape it expects. Satisfy these and your tools work; the rest of MCP is unchanged.

Serve over Streamable HTTP

DioscHub connects to your server over Streamable HTTP — the single remote transport in the current MCP specification. Expose your server at a URL DioscHub can reach, for example https://your-mcp-server.example.com/mcp, and register that URL (see Register your server).

Caution

The deprecated HTTP+SSE transport is not supported. If your server only speaks SSE, put it behind a Streamable HTTP endpoint. The admin portal offers Streamable HTTP as the only transport type.

DioscHub does not hold a long-lived connection open to call your tools. Each tools/call opens a fresh transport, makes the call, and closes it. Your server must therefore treat every call as self-contained — do not rely on connection-scoped state carrying across calls.

Report tools by their bare name

Your server reports each tool by a plain name — get_order, cancel_order. DioscHub discovers your tools through the standard tools/list operation and invokes them through tools/call.

Inside DioscHub, each tool is bound under a qualified name that prefixes the MCP instance name:

<mcpInstanceName>_<bareToolName>

A single underscore joins the two segments. For an instance named orders, your get_order and cancel_order tools become orders_get_order and orders_cancel_order. Use the qualified name wherever DioscHub asks which tools an Assistant or Role may call. Per-tool configuration — such as approval rules — is keyed on the bare name, because it is already scoped to your one instance.

Caution

The instance name is sanitized before it becomes a prefix: whitespace turns into _, and any character outside a-zA-Z0-9_- is stripped. Two instance names that differ only by a stripped character would produce the same prefix and collide. Choose instance names that stay distinct after sanitization.

What DioscHub reads from each tool

For every tool your server reports, DioscHub reads four things:

Field	Required	How DioscHub uses it
name	Yes	The bare tool name. Everything else falls back to a default if absent, but a tool with no name is unusable.
description	Recommended	Handed to the model to decide when to call the tool. If omitted, DioscHub substitutes MCP tool: <name>, which gives the model nothing to reason about — always write one.
inputSchema	Recommended	Normalized to JSON Schema and given to the model as the tool’s parameters. An absent or empty schema becomes an empty object, so the model calls the tool with no arguments.
annotations	Optional	readOnlyHint and destructiveHint, when present, tell DioscHub whether a tool changes state. This feeds the approval-suggestion surface; see Gate state-changing tools.

Write a clear description and a precise inputSchema for every tool — they are the entire basis on which the model decides whether and how to call it.

Note

Declaring destructiveHint: true (or readOnlyHint: false) marks a tool as state-changing. That surfaces the tool as a suggested candidate for an approval gate, but it does not gate the tool on its own — an admin still applies the gate. See Consensus.

Return a standard MCP result

Return the standard MCP result shape — a content array of blocks:

return { content: [{ type: 'text', text: JSON.stringify(order) }] };

DioscHub joins the text blocks and hands that string to the model as the tool’s result. Two rules to code against:

• Put the model-facing answer in text blocks. DioscHub passes text content to the model. Other block types are not interpreted as the tool result — lead with text.
• Signal failure with isError. Returning { content: [...], isError: true } makes DioscHub treat the call as failed and surface the content as the error, rather than feeding it back as a successful result. Use it for tool-level errors the model should see and react to.

A result whose content is not an array is rejected as invalid. Keep to the standard shape.

Register your server

Register the server as an MCP instance in the admin portal (or over the admin API at POST /admin/mcp-instances). The two required fields are:

• Name — a globally-unique, kebab-case identifier (^[a-z0-9]+(-[a-z0-9]+)*$), for example orders. This becomes the qualified-name prefix, so pick one that stays unique.
• Server URL — the Streamable HTTP endpoint DioscHub connects to.

Optionally, set an auth config for static, server-to-server credentials your server requires of every caller — an OAuth 2.1 client, an API key, a bearer token, or fixed headers. This is the credential DioscHub itself presents to your server, and it is entirely separate from the per-user auth covered in Forward the user’s auth. When both are present, the per-user header takes precedence on a name collision.

A newly created instance may not appear to the model immediately

Creating an instance registers it, but its tools reach a running Assistant only after a subsequent change re-triggers discovery — toggling the instance active, editing its approval config, or restarting DioscHub. Activating or deactivating an instance re-registers its tools live. If a just-created instance’s tools do not show up for the Assistant, toggle it active to force a rediscovery.

---

Next: Forward the user’s auth to your server.