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.
| Transport | Streamable HTTP |
| Protocol versions | 2025-06-18, 2026-07-28 |
| Authorization | OAuth 2.1 with PKCE, or none |
| Client registration | Dynamic Client Registration, or a pre-registered client |
| Client name | Mystical |
| Redirect URI | https://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
readOnlyHintordestructiveHint. - 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, andtools/call.- MCP Apps (
io.modelcontextprotocol/ui). A tool that declares aui://resource of typetext/html;profile=mcp-apprenders 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.
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.
| Item | Limit |
|---|---|
| Tools per server | 500 |
| Tool description | 400 characters |
| Parameter description | 180 characters |
| Input schema | 8,000 characters |
| Tool name, including the connector prefix | 64 characters |
| Tool result passed to the model | 6,000 characters |
An MCP Apps view must be under 5 MB.
Publish a connector
Publishing happens from your profile.
- 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.
- 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.
- Skills. Optional. Import them from your server, or write or upload them. See Skills.
- 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.
- Version. A version number such as
1.0.0, with release notes for later versions. - 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.zipor.skillarchive. - 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.mdfrontmatter differs from the entry'sfrontmatter. - 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
| Item | Limit |
|---|---|
| Skills per connector | 20 |
| Name | 48 characters: lowercase letters, numbers and hyphens |
| Description | 400 characters |
SKILL.md | 15,000 characters after the frontmatter |
| Supporting files | 30 per skill, text only, 100,000 characters each |
| All supporting files | 300,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:
| Statement | What you agree to |
|---|---|
| Mystical's terms | The Terms of Service and Privacy Policy. |
| Honest listing | The listing describes what the connector actually does. |
| Ownership | You own the server or are authorized to publish it. |
| User data | The connector collects only what it needs and shares it with no one undisclosed. |
| Actions with consequences | Tools are clear about their side effects, including their annotations. |
| Upkeep | You 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.
| State | Meaning |
|---|---|
| Draft | Editable. Visible only to you. |
| In review | Locked while it is reviewed. Withdraw it to make changes. |
| Live | Approved and listed in the directory. |
| Superseded | Approved, then replaced by a later version. |
| Changes needed | Not 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 server | What users get |
|---|---|
| A tool's definition changes | The approved definition, until a version with the change is approved. |
| A tool is added | Nothing. The tool becomes available once a version that includes it is approved. |
| A tool is removed | The 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.