minddy MCP

minddy MCP lets an external assistant use minddy tools under your account’s access. Connect the assistant through the instance’s setup flow, review or revoke its access in account settings, and read the current tool schemas before changing issues, pages or routines.

Connect an external assistant to minddy MCP

Open the instance's public MCP setup page and choose the instructions for your client. Use the endpoint displayed there, ending in /api/mcp. For self-hosting, use your instance origin, not the Cloud origin. The client must support the remote MCP connection and OAuth flow shown by the guide.

Complete sign-in in the browser and inspect the authorization request before granting access. The connection acts as your minddy account; it does not obtain access to projects you cannot use. Start with a read request for an issue you can already open, then check that the returned project is the intended one.

Select your client to display its installation command or configuration.

MCP availability and network access

MCP is included in self-hosted minddy and starts with the application. It works out of the box at /api/mcp on the instance origin configured with MINDDY_PUBLIC_APP_URL. OAuth discovery and dynamic client registration are included: you do not need a separate MCP server, a dedicated OAuth application or a minddy Cloud proxy. Connect your MCP client to your instance endpoint, then sign in and grant access through the browser consent flow.

Availability does not guarantee network reachability. Both the MCP client and the browser used for authorization must be able to reach the advertised MCP and OAuth URLs. If you configure an explicit OAUTH_ISSUER override, that origin must also be reachable. The client must support the connection, OAuth flow and chosen network path; some clients require HTTPS even on private networks.

• Same computer: http://localhost:6463/api/mcp works for a compatible client running on the computer hosting the local instance. localhost and 127.0.0.1 refer to the computer making the connection. The desktop local-instance launcher listens only on loopback; another computer or a hosted/cloud agent cannot reach it directly. Opening the server’s localhost URL on another computer points to that other computer.

• LAN or VPN: an instance configured as http://192.168.1.50 advertises http://192.168.1.50/api/mcp. A client on the LAN, or connected through a VPN, can use it if the listening address, configured origin, application port, firewall and routing allow access. The browser must reach the same advertised authorization URLs. This requires a reachable server installation; changing the client URL alone does not expose a loopback-only process.

• Outside the private network: use a reachable HTTPS origin, for example https://tickets.example.com/api/mcp, or another network path supported by the client. A hosted agent needs its own route to the instance; a VPN on your browser’s computer alone does not provide that route. Hosting minddy locally does not automatically expose it to the Internet.

Scope and revocation

External clients can use available minddy tools for issues, plans, comments, pages, feedback, cycles, routines and the task notebook within their authorized permissions. Tools follow your current role in each project on every call, so a role change applies without reconnecting. As a reader you get the read tools, plus the comment tools when the owner turned on Can comment for you. The MCP server is available on every Cloud plan; running the client's AI still depends on that client's configuration and costs.

Account settings' minddy MCP section lists external client access and its revocation controls. Revoke a client when you no longer trust or use it. This is separate from the MCP for Numo card in the AI & Numo tab, which connects Numo to other services. Never paste access tokens into issues, public feedback or screenshots.

This example connects to minddy Cloud. For self-hosting, use your own instance origin; the displayed command was not executed for this capture.

Use minddy MCP safely and discover its current tools

minddy exposes /api/mcp with Streamable HTTP, stateless tools and OAuth 2.1. Connect as your own account through browser consent; old static mdyk_ keys are not accepted. Start with minddy_list_projects to obtain accessible project UUIDs, then read the connected server tool schemas. /llms-full.txt is generated from those registrations and provides the exact current parameters. Do not guess tools from an old copied list. Project-scoped tools recheck access and return stable error codes.

Read issues before changing their plans

To find an issue, call minddy_list_issues with query: it matches title and description words, an identifier or a number. Text matches and exact identifiers come first; a descriptive query can then add issues of the same project found by meaning, marked match: "semantic". Read such an issue before acting on it. Search by meaning is charged to your account as Issue search and is skipped when you turned off Index issues.

minddy_get_issue accepts an issue UUID, an issue identifier such as DEMO-42, or a bare issue number; project_id is supplied separately. Its plan_tasks provide zero-based task_index values. minddy_update_plan_task accepts a tasks batch with pending, in_progress, completed or cancelled states. The whole batch fails on an invalid index. Use minddy_append_to_plan for additions and minddy_edit_issue_text with a unique exact old_string/new_string for a passage. Re-read if the match is stale; replacing the entire plan can overwrite another person’s progress. Questions under ## Questions do not count as plan tasks.

Reads that return text with images (minddy_get_issue, minddy_get_objective, minddy_get_page, minddy_get_feedback, minddy_get_scratchpad) list them under images, each with its src and alt text. Pass that src exactly to minddy_get_image: it checks your access to the image's project, or that a notebook image is yours, and returns the image inline up to 10 MB with a signed download_url valid about ten minutes. An image hosted outside minddy comes back as its URL only.

Use revision guards and owner scope

minddy_list_pages maps hierarchy; minddy_search_pages finds title/body excerpts and minddy_get_page reads the full Markdown, comments and database values. Use append/edit tools for partial changes and current version guards for full replacement. Preserve file/image URLs exactly. minddy_create_page with database=true creates a database; minddy_update_page_database requires the database revision for schema edits and the previous value for cell edits.

For a type conversion, use operation=convert with propertyId, targetType, revision and preview=true. Inspect incompatibleCount, then submit the same settings with preview=false and the returned token. Set confirmLoss=true only after the user explicitly authorizes clearing incompatible values.

Owner-only routine tools create, change, pause or remove routines with a schedule, an event or a new database entry as their trigger. Read existing routines first to avoid duplicates. Resource uploads through minddy_add_resource are capped at 10 MB; page tools do not invent file URLs.

Verify the returned state

The sanitized example updates the first task of an already-read plan. Replace the project UUID and issue with values from discovery; task_index must come from the latest read. Confirm returned plan_tasks and plan_progress. On access errors, check the account/project authorization; on stale conflicts, read again and apply only the intended change. Do not retry an uncertain external mutation before checking its result.

{
  "project_id": "00000000-0000-4000-8000-000000000001",
  "issue": "DEMO-42",
  "tasks": [{"task_index": 0, "state": "in_progress"}]
}

Choose an objective for feedback

Feedback reads include objective_id; minddy_list_feedback accepts an optional objective filter (null selects requests without an objective). Use minddy_link_feedback_objective with project_id, feedback_post_id and objective_id only when the user explicitly requests the association; null clears it. The objective must be active and in the same project. Objective detail reads include linked_feedback. The owner can supply objective_id to minddy_create_integration for a feedback key, or change the default with minddy_update_integration_objective. Existing feedback keeps its choice. Promotion inherits the objective and categories, and Numo review never assigns an objective.