---
title: "Replace or clear the signed-in user’s custom MCP server instructions overlay (appended to built-in server instruction..."
method: PUT
path: "/v1/mcp-server-instructions"
tags: ["memories"]
---

# Replace or clear the signed-in user’s custom MCP server instructions overlay (appended to built-in server instruction...

`PUT /v1/mcp-server-instructions`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/mcp-server-instructions`
- Auth: HTTP bearer

Replace or clear the signed-in user’s custom MCP server instructions overlay (appended to built-in server instructions for new MCP connections). Put guidance at the right layer: see search({ entity: "guide:agent_guidance" }) (Where agent guidance lives / /docs/agent-guidance). Prefer memories for durable facts and preferences; use this overlay only for rare always-on session policy—not package inventory, export gotchas, or package docs. Pass an empty string to clear. Changes apply to new MCP sessions—reconnect the client if the host caches server instructions. Reports assembled_chars and a warning when some clients would truncate the overlay.

Org permission: `org:write`.

## Request body

- object
  - `instructions` string, required: Full replacement text for the user overlay, or empty string to remove it.

## Response `200`

Success.

- object
  - `ok` true, required
  - `max_length` integer, required
  - `instructions` string, nullable, required
  - `assembled_chars` integer, required
  - `warning` string, nullable, required

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

[API](https://skmtc.dev/kody/apis/kody-api.md) · [All operations](https://skmtc.dev/kody/apis/kody-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kody/apis/kody-api/revisions/a020ecedb82b?raw)