Code Mode MCP

Shiplet MCP lets agents discover the API, then call it through code. Interactive clients authenticate through browser OAuth; CI can use a least-privilege organization key.

Endpoint

https://shiplet.cc/api/mcp

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

First connection

For a concrete client, create .vscode/mcp.json in VS Code:

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

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

1. Add the endpoint as a remote MCP server in a client that supports OAuth protected-resource discovery.
2. Start the connection. The first protected request returns an OAuth challenge; complete AuthKit in the trusted browser window and return to the MCP client. Do not paste a token into the client or package code.
3. Call tools/list and confirm the kernel tools are search and execute.
4. Run search before execute so the agent uses the current operation, authentication, scope, and Code Mode markers.

Stable kernel tools

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": { "code": "async () => await codemode.spec()" }
  }
}

Search can discover public REST routes that Code Mode does not execute. Check each operation's x-shiplet-code-mode marker in OpenAPI; use the browser or direct REST path for an unsupported operation.

Packages may declare additional active-revision tools under shiplet.<shiplet>.<revision>.<tool>. They cannot shadow kernel or sibling tools.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute",
    "arguments": {
      "code": "async () => await codemode.request({ method: 'GET', path: '/api/shiplets' })"
    }
  }
}

Scope custom tools

Custom discovery and invocation require the logical Shiplet ID in request metadata:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/list",
  "params": { "_meta": { "shipletId": "project_123" } }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "shiplet.project_123.revision_7.summarize-review",
    "arguments": {},
    "_meta": { "shipletId": "project_123" }
  }
}

Without _meta.shipletId, tools/list returns only kernel tools and a custom call fails with custom_shiplet_scope_required. A correctly scoped custom call runs only when the exact isolated-runtime support release is attested; otherwise it fails closed with runtime_unavailable. The authenticated deployment-status API is authoritative for live readiness.

Trust package tools as data

Custom descriptions, schemas, handler output, and results are untrusted package content. A handler receives only declared and granted capability handles. Side effects pause for trusted approval and bind the invoker, approver, Shiplet, revision, tool, effect, and input.

A project-authorized agent with shiplets:write can promote or roll back with explicit approval; the kernel attributes, audits, and concurrency-fences that effect. Customer-owned deployment requires a trusted human session.

Next: read the API surface and route ledger, custom MCP and workflow contracts, or verify the authority boundary.