Connect an agent

Connect an MCP-compatible client to the Misaki Studio desktop application at http://localhost:16472/mcp. Once connected, test the server with a read-only list-projects request before authorizing any project change.

Coverage: Desktop required. The packaged application starts the production MCP server; the website alone does not provide this local endpoint.

Before you connect

You need:

• the Misaki Studio desktop application installed and running;

• at least one local Misaki Studio profile;

• an MCP client that supports Streamable HTTP servers;

• permission to edit that client's MCP configuration.

The server starts with the packaged application and stops when the application closes. Keep Misaki Studio running while the agent works.

Add the production server

The default production endpoint is:

http://localhost:16472/mcp

Use misaki-studio as a recognizable server name. The exact configuration location and surrounding format depend on the MCP client, but the server entry is commonly shaped like this:

{
  "mcpServers": {
    "misaki-studio": {
      "type": "http",
      "url": "http://localhost:16472/mcp"
    }
  }
}

Save the configuration, then reconnect or restart the MCP client so it reloads the server and its current tool schemas. If the product adds or changes tool parameters while a client session is open, reconnect before assuming the new schema is unavailable.

This is the public packaged-app connection. Repository development servers can use different ports; they are maintainer environments and are not substitutes for the visitor setup above.

Test the connection without changing a project

Ask the agent:

Use the Misaki Studio MCP server to call list-projects. Do not select, create, rename, delete, publish, or edit anything. Show me the project names and IDs returned by the server.

A working connection returns the available projects or a clear message that no profile/project exists. list-projects does not select a project and does not authorize later mutation.

Next, follow Select a project safely.

If the connection fails

Check these in order:

1. Confirm the desktop application is still open.

2. Confirm the client URL is exactly http://localhost:16472/mcp, including /mcp.

3. Reconnect or restart the MCP client.

4. Check whether another process already owns port 16472. The app can choose a higher free port when its default is occupied, but an MCP client configured for 16472 does not follow that move automatically. Free the default port and relaunch, or point the client at the port the app actually bound.

5. If list-projects says No profile found. Create one first., create or sign in to a profile in Misaki Studio, then retry.

6. If project tools say No project selected, the connection works; select a project for this session.

7. If a preview/export operation reports that the app websocket is not connected, keep the desktop app running and retry after the host is ready. Basic project access and host-assisted rendering are separate dependencies.

Do not switch a public setup to the repository's development port merely because the production endpoint is unavailable. That can connect the agent to a different data directory or development stack.

Security: treat the connection as project access

The current MCP route has no separate authentication prompt or token. A client that can reach it can use tools that read, change, export, publish, or delete project data according to the tool called.

• Connect only trusted agents and MCP clients.

• Do not port-forward, tunnel, proxy, or publish the MCP port.

• Use the computer's firewall to block unwanted incoming connections, especially on shared or public networks.

• Ask the agent to show its target and obtain confirmation before deletion, publishing, Git, or other external operations.

• Close Misaki Studio when you do not want the packaged MCP endpoint running.

localhost in the client URL describes how that client reaches the service; it should not be treated as an authentication boundary.

What connection does not do

Connecting the server does not:

• select a project;

• force the agent to use the project currently visible in the editor;

• grant permission for every destructive or external action;

• guarantee that the connected client has refreshed a recently changed tool schema;

• prove that preview/export host operations are healthy.

Establish those facts explicitly in the task.