Code Mode MCP

Shiplet MCP lets an agent discover the supported API and call it through code. Interactive clients authenticate in the browser. A registered external agent can request access to one Shiplet organization when the environment enables agent registration.

Endpoint

https://shiplet.cc/api/mcp

OAuth discovery is available at https://shiplet.cc/.well-known/oauth-protected-resource.

Connect from VS Code

{
  "servers": {
    "shiplet": {
      "type": "http",
      "url": "https://shiplet.cc/api/mcp"
    }
  }
}

This follows VS Code's remote HTTP MCP configuration. Keep credentials out of the file because Shiplet hands sign-in to the trusted browser.

1. Add the endpoint as a remote HTTP MCP server.
2. Complete the first protected request through Shiplet sign-in.
3. Call tools/list and confirm search and execute.
4. Run search before execute.

Connect an agent to Shiplet

https://shiplet.cc/auth.md

Shiplet supports registered agents through the Code Mode MCP endpoint. The agent follows the guide, asks you to approve access in the browser, and connects to the Shiplet organization you choose.

What the agent can do

The registered agent uses the same search and execute tools as any Code Mode client. It can discover Shiplet operations, publish or update Shiplets, and work with review feedback when its permissions allow those actions.

Shiplet recognizes these agent permissions: mcp, shiplets:read, shiplets:write, feedback:read, and feedback:write. Current organization membership and Shiplet grants still apply to every request.

Approve access

1. Give the agent https://shiplet.cc/auth.md.
2. Open the browser approval link it returns, sign in, and choose the Shiplet organization the agent can use.
3. Return to the agent after the approval page confirms access. The agent connects to https://shiplet.cc/api/mcp.

The registration remains a distinct agent actor in Shiplet's audit history. Your user identity records who approved it, and the selected organization sets the boundary for its work.

Check the connection

1. Ask the agent to call tools/list. Shiplet returns exactly search and execute.
2. Run a harmless authorized read, such as GET /api/shiplets through execute.
3. A 401 means the agent needs to reconnect. A 403 means its selected organization, current membership, Shiplet grant, or required permission does not authorize the operation.

The agent client owns its connection credentials. Keep those credentials out of Shiplet uploads, review feedback, and custom widgets.

Core tools

• search discovers the public OpenAPI contract.
• execute calls supported operations through codemode.request(...).

Those are the complete top-level tool catalog. Shiplet never adds a third tool from an artifact or custom widget. The JavaScript passed to either tool runs in an isolated Worker without network access or credentials, and API calls return to Shiplet's authenticated host.

search builds an authorization-specific OpenAPI view. A broad path search can find the trusted, paginated /api/shiplets/custom-mcp-catalog operation. Call that through execute, choose an accessible active Shiplet, then search its returned literal /api/shiplets/{id}/custom-mcp/ prefix. Each operation appears at a concrete revision-fenced path and can run only through execute. The focused request reads only an immutable, digest-bound MCP projection and referenced handlers, not unrelated package files. An operation is omitted when its isolated runtime is unavailable or the active configuration changes.

Shiplet supplies the operation description shown to the model and validates the declared input schema. Configuration-authored prose and handler output stay in quarantine; execute returns only a platform-owned completion notice unless a trusted person explicitly reviews the quarantined content.

Each operation carries an x-shiplet-code-mode marker. Use direct REST or the browser when an operation is outside that surface.

Prepare an artifact

async () => await codemode.request({
  method: "POST",
  path: "/api/shiplets",
  body: { name: "Prototype", subdomain: "prototype", assets: [...] }
})

Customize the review widget

Read the current review layer, prepare a preview from widget-relative changes, and apply the preview after a person approves it. The version returned by the first request prevents a stale preview from replacing newer work.

async () => {
  const layer = await codemode.request({
    method: "GET",
    path: "/api/shiplets/project_123/review-layer"
  });
  return { version: layer.version, paths: layer.files.map(file => file.path) };
}

Run search for the preview and apply request schemas before writing. These operations only accept review-widget files, so the artifact stays unchanged.

Read feedback

async () => await codemode.request({
  method: "GET",
  path: "/api/projects/project_123/review-feedback"
})

Authentication and authority

Browser OAuth identifies an interactive user. A registered agent remains a separate actor in Shiplet's audit history, tied to the user who approved it and the selected organization. Its effective authority combines recognized agent permissions, current Shiplet membership and grants, the selected organization, and the requested operation. Unknown permissions grant nothing.

Next: connect through browser OAuth, or ask a compatible agent to follow https://shiplet.cc/auth.md, then run search.