Mystical Platform

Connectors

Mystical is an MCP client. People connect remote Model Context Protocol servers to Mystical and use their tools in Chat and in Tasks, including tasks that run unattended. This guide covers how Mystical connects to a server and how to publish one to the Mystical directory.

Overview

There are two ways a server reaches Mystical users:

  • Directory connectors. Published through the Mystical Platform and reviewed by Mystical before they are listed. Anyone can find and connect them.
  • Custom connectors. Added by a user from the server's URL, for their own account only. No review is involved.

Both use the same client, described below.

TransportStreamable HTTP
Protocol versions2025-06-18, 2026-07-28
AuthorizationOAuth 2.1 with PKCE, or none
Client registrationDynamic Client Registration, or a pre-registered client
Client nameMystical
Redirect URIhttps://api.chatmystical.com/mcp/connections/callback

Requirements

To be listed in the directory, a server must:

  • Be remote and reachable at a public HTTPS URL. Local and private-network addresses are refused.
  • Speak MCP over Streamable HTTP.
  • Use OAuth 2.1 if its tools act on a user's account. A server that only serves public data can be unauthenticated.
  • Describe each tool accurately, and annotate it with readOnlyHint or destructiveHint.
  • Have a public documentation URL and privacy policy URL.

Transport and protocol

Mystical sends JSON-RPC requests as HTTP POST and accepts either application/json or text/event-stream responses. If the server issues an Mcp-Session-Id, Mystical returns it on every later request.

The client offers protocol version 2025-06-18 in initialize and accepts the version the server chooses. If a server rejects initialize, Mystical retries with 2026-07-28.

Supported features

  • tools/list, with pagination, and tools/call.
  • MCP Apps (io.modelcontextprotocol/ui). A tool that declares a ui:// resource of type text/html;profile=mcp-app renders as an interactive view in the conversation.
  • Skills over MCP (io.modelcontextprotocol/skills), for importing a server's skills into its directory listing. See Skills.

Prompts, sampling, elicitation and roots are not supported.

Authorization

When a server answers with 401 Unauthorized, Mystical runs the OAuth 2.1 authorization code flow as the MCP authorization specification describes.

  • Discovery. Protected resource metadata (RFC 9728), from the resource_metadata parameter of WWW-Authenticate when it is on the server's own origin, otherwise from the well-known location. Authorization server metadata (RFC 8414), falling back to OpenID Connect discovery.
  • Registration. Dynamic Client Registration (RFC 7591), with the client name Mystical and the grant types authorization_code and refresh_token. For an authorization server without it, the publisher enters a pre-registered client ID and secret when submitting the connector.
  • PKCE. S256 only. Mystical will not connect to an authorization server that advertises PKCE methods without S256.
  • Resource indicators. The resource parameter (RFC 8707) is sent with the authorization request, so a token is issued for your server alone.

Register this redirect URI with your authorization server: https://api.chatmystical.com/mcp/connections/callback

Access tokens are refreshed automatically, encrypted at rest, and deleted when the user disconnects.

Tools and approvals

Users control what each tool may do: Always allow, Needs approval or Blocked. By default Mystical asks before a tool runs. An approval covers the tool as it was described at the time: if its definition changes, Mystical asks again.

Tools are grouped by their annotations. A tool with readOnlyHint: true is listed as read-only; any other tool is treated as one that writes or deletes. Tools with an MCP Apps view are listed as interactive.

Tool names are prefixed with the connector's identifier, so tools from different servers never collide. When a user's tool definitions exceed about 4,000 tokens, Mystical shows the model every tool's name instead, with a one-line summary when there is room, and loads full definitions as needed. For the largest catalogues, the model sees each connector's subtitle and searches its tools. Every tool stays available either way, so write names and subtitles that say what a tool or connector is for.

Recommendations

  • Keep reading and writing in separate tools, rather than one tool with a method parameter.
  • Write descriptions for the model: what the tool does and when to use it, in a sentence or two.
  • Return errors that say what went wrong and how to fix it.
  • Ask only for the data the tool needs.

Limits

Mystical trims content past these limits rather than refusing the server. Tools past the first 500 are ignored, long text is shortened, and an oversized input schema loses optional properties first; required parameters are always kept.

ItemLimit
Tools per server500
Tool description400 characters
Parameter description180 characters
Input schema8,000 characters
Tool name, including the connector prefix64 characters
Tool result passed to the model6,000 characters

An MCP Apps view must be under 5 MB.

Publish a connector

Publishing happens from your profile.

  1. Platform details. Your platform name, shown to users as “Made by”, and a contact email for review updates. An address other than your account's is confirmed with a code.
  2. Server. Enter your server URL. Mystical connects to it, confirms it speaks MCP, detects how it authenticates and lists its tools, and any skills it serves. For an OAuth server, sign in when asked so they can be listed.
  3. Skills. Optional. Import them from your server, or write or upload them. See Skills.
  4. Listing. Name, subtitle, description, one to three categories, a square PNG icon (128 to 1,024 px), and links to your website, documentation, privacy policy and terms of service. Every link is checked before submission.
  5. Version. A version number such as 1.0.0, with release notes for later versions.
  6. Submit. Accept the policy statements and submit the version for review.

Drafts are visible only to you.

Skills

A connector can ship with Agent Skills: instructions the assistant follows when a task matches them, such as how to use your tools well or a complete workflow. A skill is a SKILL.md file with name and description frontmatter, plus optional supporting text files. Skills are installed with the connector, and users can turn each one off.

Adding skills

  • Import from your server. If your server implements Skills over MCP, the scan lists its skills and you choose which to import.
  • Upload. A SKILL.md, a skill folder, or a .zip or .skill archive.
  • Write. In the editor on the submission form.

Importing from your server

Your server declares the io.modelcontextprotocol/skills extension in its capabilities. Mystical lists skills with skills/list, reads each one you import with skills/get, and fetches its files with resources/read. An import is refused if:

  • A file's size or SHA-256 digest differs from the skill's entry.
  • The SKILL.md frontmatter differs from the entry's frontmatter.
  • The skill declares "resources": "dynamic", so there is no fixed content to review.
  • Two skills on the server share a name. Import one of them.

Supporting files that are not text, or that exceed the limits below, are left out, and the form lists them. For an OAuth server, sign in on the form first.

An imported skill is a copy. It is security-scanned and reviewed with the version, and users get the reviewed copy, never the live server's files. Mystical checks your server regularly. If a skill changes, a new one appears, or one is removed, your Connectors dashboard shows it and you are emailed. To ship the change, scan your server in a new version and import the update.

Skill limits

ItemLimit
Skills per connector20
Name48 characters: lowercase letters, numbers and hyphens
Description400 characters
SKILL.md15,000 characters after the frontmatter
Supporting files30 per skill, text only, 100,000 characters each
All supporting files300,000 characters per skill

Review

Mystical reviews every version before it is listed. Tool descriptions become instructions in other people's conversations, so reviewers check that the server works, that its tools do what they say, that annotations match their behavior, and that the listing describes the connector accurately. The tool definitions captured at submission are the ones reviewed.

When you submit, you affirm six statements:

StatementWhat you agree to
Mystical's termsThe Terms of Service and Privacy Policy.
Honest listingThe listing describes what the connector actually does.
OwnershipYou own the server or are authorized to publish it.
User dataThe connector collects only what it needs and shares it with no one undisclosed.
Actions with consequencesTools are clear about their side effects, including their annotations.
UpkeepYou keep the server working and ship tool changes as new versions.

An approved version goes live in the directory. If changes are needed, the version is returned with a note explaining why, and you can submit again.

Versions and updates

Each submission is a version. A new version must be numbered higher than the live one and include release notes. The live version is unaffected while the new one is in review.

StateMeaning
DraftEditable. Visible only to you.
In reviewLocked while it is reviewed. Withdraw it to make changes.
LiveApproved and listed in the directory.
SupersededApproved, then replaced by a later version.
Changes neededNot listed. Returned with a note.

Reviewed tools

Users of a directory connector get the tool definitions that were approved. Mystical checks listed servers regularly and handles changes to the live server as follows:

Change on your serverWhat users get
A tool's definition changesThe approved definition, until a version with the change is approved.
A tool is addedNothing. The tool becomes available once a version that includes it is approved.
A tool is removedThe tool is removed immediately.

A definition is a tool's name, title, description, input and output schemas, annotations and _meta. Detected changes appear on your Connectors dashboard and are emailed to you, at most once a day. To ship them, submit a new version.

Unpublishing

Unpublishing removes a connector from the directory. People who already connected it keep access. Publishing it again takes effect immediately, without another review. A connector can only be deleted once no one is connected to it.