# Knotbind — full public documentation This file is generated from the guides published on docs.knotbind.com. It contains public product and usage documentation only; internal planning and repository files are excluded. ## Safe actions between AI agents and businesses. Source: [Start here](https://docs.knotbind.com/docs/start) Knotbind sits between an assistant and a business's software. Agents can look things up and ask for changes; a person releases anything that matters; and Knotbind keeps the connection working as the software changes. The idea ## An agent may ask. Only a person may release. An assistant can find a business, read what it offers and start a booking, an order or a refund. What it may do on its own, what waits for the Owner, and which secrets it never sees are decided by the business, in advance, and recorded on every step. Agent→Knotbind→Business MCP→Data ## What makes it safe Layer | What it does | Read more | Risk classes and policies | Reads and quotes run on their own. Creating, paying and cancelling wait for the Owner unless a policy the Owner wrote says otherwise, within a cap. | Write actions (https://docs.knotbind.com/docs/write-actions) | Credential vault | An agent is given the right to run one operation, never the upstream secret. | Credential vault (https://docs.knotbind.com/docs/credential-vault) | Monitoring | Scheduled Checks and a Baseline notice when the business's software changes in a way that breaks an agent. | MCP servers (https://docs.knotbind.com/docs/mcp-servers) | Audit Record | Every step, approval and change is written down with who did it. | Glossary (https://docs.knotbind.com/docs/glossary) | ## Which path is for me? 01 ### I want to see it work Try the public demo. Nothing on it touches another company's product. 02 ### I run an MCP server Connect it with three calls and get contract Checks, a Baseline and drift alerts. 03 ### I am building an agent The REST and MCP API: responses, errors, limits, retries and how an agent learns an approval is pending. 04 ### I own a business Decide what an agent may do on its own, with a worked booking example. 05 ### My code calls Stripe, OpenAI, GitHub or Twilio Mend opens a fix pull request when one of those APIs changes. 06 ### I run an LLM app The Gateway, with an access key, a budget and optional modules. ## What Knotbind fixes, and what it does not Knotbind is several products with different buyers. This is what "repair" means in each, and who does it. Product | What gets repaired | Where | Who makes the change | Monitoring | Knotbind's own Check, so it matches the changed API. | Knotbind | The Owner approves. Your API and repository are not touched. | Monitoring, Business plan | The approved change, sent on. | Your deployment webhook, or one pull request in your repository | You review and merge. Nothing is deployed by approving. | Mend | Your code, when a third-party API changes. | A draft pull request on GitHub, in TypeScript or Python repositories | You review and merge. Mend never writes to a default branch. | Build | Not included. A generated server is a starting point. | Your repository | You. Review of an updated contract is offered, not applied. | Important boundary A contract Check proves that your endpoint speaks MCP and returns the expected result. It does not claim that Claude, ChatGPT or Cursor has connected. Real client proof is recorded separately or detected live through the relay. ## Watch Knotbind on the public demo. Source: [Try the demo](https://docs.knotbind.com/docs/quickstart) The public demo is a Knotbind workspace with a Knotbind-owned MCP server. Nothing on it writes to another company's product. - ### Open the demo The demo page (https://www.knotbind.com/demo) has Enter the demo. That opens the shared workspace. It is not Sign in, which is for a customer workspace. The demo can look through Checks, Gateway modules, alerts, and audit history. It cannot change settings, keys, or the GitHub connection. - ### Connect an assistant to the showroom Point Claude, ChatGPT, or another MCP client at `/demo/mcp` on this site. The server exposes tools, resources, prompts, and a hold-then-confirm write that stays inside the demo. Write tools pause until you allow them. - ### Break a private copy Add your email and a Slack incoming-webhook URL. After you confirm the email, you can rename a field, remove a tool, force an error, or require a new query parameter. That break lasts 30 minutes and does not change what other visitors see. - ### Read the repair Knotbind records the failed Check. When the demo GitHub account is configured, it opens a pull request on the demo repository and closes it later. It does not merge. Shared workspace The showroom breaks itself for the first ten minutes of each UTC hour, then returns to the same Checks. Use a private run when you want to choose the break. A live third-party MCP server is listed, never written to, and is not part of this public demo. ## Connect an MCP server in three calls. Source: [Connect your server](https://docs.knotbind.com/docs/connect-your-server) Create a workspace, connect your server, read the result. No browser is needed, and every command below is a real call against this site. ## 1. Create a workspace ```sh curl -sS -X POST https://www.knotbind.com/api/v1/signup \ -H 'content-type: application/json' \ -d '{"company":"Your company","name":"Integration Agent","email":"you@example.com"}' ``` ```json { "account": { "id": "8f2c1d4e9a7b3c05", "company": "Your company" }, "api_key": "kbk_...shown once...", "scopes": ["read", "write"], "next": "Call connect_mcp_server with your MCP server URL." } ``` The `api_key` is shown once. Keep it as `KNOTBIND_API_KEY`. Sign-up is limited to five per hour per client address, and one email can own one workspace. Use an address a person reads: it is where alerts and approval requests go, and the only way a person opens the dashboard is Forgot password with that address. ## 2. Connect your MCP server ```sh curl -sS -X POST https://www.knotbind.com/api/v1/integration \ -H "authorization: Bearer $KNOTBIND_API_KEY" \ -H 'content-type: application/json' \ -d '{"mcp_url":"https://api.example.com/mcp"}' ``` ```json { "connected": true, "onboarded": true, "tools": [ { "name": "search_products", "read_only": true }, { "name": "create_order", "read_only": false } ], "checks": [ { "id": "search-products", "tool": "search_products", "arguments": { "query": "example" } } ], "baseline_run": { "id": 1, "passed": true, "latency_ms": 212 }, "next": "Monitoring is on. Call get_status any time." } ``` Knotbind discovers the tools and turns on monitoring for up to three tools that the server itself marks read-only and whose arguments it can fill from declared defaults, examples or enums, so a scheduled Run never writes data. If no tool qualifies you get `422 no_read_only_tools` with the tool names. For every other tool, Knotbind suggests a contract Check built from the tool's declared input and output schemas. A suggestion is not a Check: the Owner approves each one in the dashboard before it runs on a schedule. How many are active at once is set by your plan (Free 3, Pro 10, Business 25), so approve the tools that matter most; the rest stay suggestions. ## 3. Read the result ```sh curl -sS https://www.knotbind.com/api/v1/status \ -H "authorization: Bearer $KNOTBIND_API_KEY" ``` ```json { "health": "healthy", "consecutive_failures": 0, "finding": { "status": "none" }, "last_run": { "id": 14, "passed": true, "latency_ms": 198 } } ``` `health` is `healthy`, `suspect` (a Check failed once) or `failing`. A Finding opens after two consecutive failures or on Breaking Drift. Healthy means `health` is `healthy`, `finding.status` is `none` and `last_run.passed` is true with a recent time. ## Next - MCP servers (https://docs.knotbind.com/docs/mcp-servers): several servers, Baselines, workflow Checks and drift alerts. - Agent API (https://docs.knotbind.com/docs/agent-api): every endpoint, error and limit. - MCP and OAuth (https://docs.knotbind.com/docs/mcp): connect Claude, ChatGPT or Cursor to Knotbind itself. ## Everything in the dashboard, as JSON. Source: [Agent API](https://docs.knotbind.com/docs/agent-api) The REST API, the Knotbind MCP server and the CLI share one service layer. Use the API for automation, MCP for tool-using agents, and the CLI for scripts and operators. ## Endpoints Surface | URL | Authentication | OpenAPI | /openapi.json | Public | REST | /api/v1/* | Bearer kbk_… or OAuth kbo_… | Knotbind MCP | /mcp | OAuth 2.1 or Bearer | CLI | bin/knotbind.mjs | KNOTBIND_API_KEY | New here? Connect your server (https://docs.knotbind.com/docs/connect-your-server) walks the first three calls with their responses. ## Core calls Call | What it does | POST /api/v1/signup | Public. Returns a kbk_ key once. | POST /api/v1/integration | Connect an MCP server and start a Baseline. | GET /api/v1/status | Health, current Finding and last Run. | GET /api/v1/runs, POST /api/v1/runs | Run evidence, or run every Check now. | GET /api/v1/finding | The current Finding with its diagnosis. | POST /api/v1/tools/call | One deliberate tool call. Does not create a Check. | GET /api/v1/actions/providers | Find the businesses an agent may act on. | POST /api/v1/actions/workflows/start | Start a workflow. See Write actions. | GET /api/v1/actions/runs/{id} | Poll a run: status and current step. | POST /api/v1/memory, GET /api/v1/memory/recall | Agent memory. | ## Scopes Scope | Can do | Cannot do | read | Status, Runs, Findings, tools, assistant connections, plan, memory recall | Change Checks or run a write operation | write | Everything in read plus connect, run, add and remove Checks, one-time tool calls, remember and start workflows | Approve, reject or deploy production changes | tool:execute, tool:execute:write | Narrower scopes an Owner can give one key in the dashboard, for one-time tool calls | Anything else | A key from sign-up has read and write. An Owner revokes keys at any time. A write-capable one-time tool call also needs `"allow_write": true`. ## Responses A successful call returns the object itself, with status 200, or 201 when it creates something. A read of the current state: ```json GET /api/v1/status { "health": "healthy", "consecutive_failures": 0, "finding": { "status": "none" }, "last_run": { "id": 14, "passed": true, "latency_ms": 198 } } ``` One deliberate tool call: ```json POST /api/v1/tools/call { "tool": "search_products", "arguments": { "query": "shoes" } } { "tool": "search_products", "ok": true, "duration_ms": 187, "result": { "content": [] } } ``` ## Errors and what to retry Every error is JSON, and the `code` is stable enough for an agent to act on: ```json { "error": { "code": "plan_limit", "message": "The Free plan includes up to 3 Checks." } } ``` Status | Code | Retry? | 400 | invalid_input, invalid_json, invalid_url, invalid_tool_arguments | No. Fix the request. | 401 | unauthorized, invalid_token | No. Send a valid key or refresh the OAuth token. | 403 | forbidden, tool_write_scope_required, actions_stopped | No. The key lacks a scope, or an Owner stopped agent actions. | 404 | unknown_tool, action_not_found, workflow_not_found | No. | 409 | exists, not_connected, write_consent_required, tool_definition_changed | No. Change the request or get consent. | 413 | too_large | No. Bodies are limited to 100 kB. | 422 | no_read_only_tools, sensitive_data_blocked | No. | 429 | rate_limited, too_many_tool_calls | Yes, after a pause. | 502 | mcp_unreachable, tool_call_failed, tool_error | Reads yes. Writes: check the upstream system first. | 503 | server_unavailable, busy | Yes, after the time the message gives. | ## Limits Limit | Value | REST requests | 120 per minute per workspace | MCP tool calls at once | 4 per workspace | Workflow starts | 30 per minute per agent | Sign-ups | 5 per hour per client address | Request body | 100 kB | Hosted MCP relay | 60 requests per minute. The reply is 429 with Retry-After: 60 | The REST API does not send rate-limit headers, so back off yourself. List endpoints that take a `limit` accept 1 to 50. ## Writes, retries and idempotency Knotbind has no idempotency key and does not deduplicate a repeated write, so do not assume a second identical call is harmless. Never retry an uncertain write until you have checked the upstream system. - `502 tool_call_failed` on a write: the server may or may not have acted. Look at the upstream system, or call a read tool of the same server, before trying again. - `502 tool_error`: the tool answered with an error. The body carries the `result`; read it before retrying. - `503 server_unavailable`: Knotbind's circuit breaker stopped contacting a server that failed three times. No call was made, and the body gives the time of the next probe, so it is safe to retry after that. - A workflow step whose outcome is unknown ends the run as `unknown` and is never retried automatically. Read `GET /api/v1/actions/runs/{id}/evidence` to see what happened. ## Approvals: how an agent finds out When a workflow stops at a step the policy does not cover, the run waits as `pending_approval` and the Owner is alerted. An agent cannot approve its own run, and it has no webhook of its own, so it polls. ```json GET /api/v1/actions/runs/action_8f2c1d4e9a7b { "run_id": "action_8f2c1d4e9a7b", "status": "pending_approval", "current_step": 2, "updated_at": "2026-11-14T18:02:11.000Z" } ``` Status | Means | pending_approval | Waiting for the Owner. Keep polling. | running | A step is in progress. | waiting | Paused between steps. | completed | Every step finished. | failed | A step failed with a known result. | unknown | A write ended without a verifiable answer. A person must look. | cancelled | Stopped by an Owner. | Poll every 10 to 30 seconds, backing off to minutes, because a person decides. `POST /api/v1/actions/runs/{id}/approve` does not approve anything: it reports whether the run is waiting and where the Owner approves it. The Owner's own systems (Slack, email, a signed webhook) are told as well; see Alerts and monitors (https://docs.knotbind.com/docs/alerts). ## An agent may ask. Only a person may release. Source: [Write actions](https://docs.knotbind.com/docs/write-actions) How a Knotbind workspace decides what an agent may change on a business's systems: what runs on its own, what waits for the Owner, and what can be undone. ## The short version An agent that wants to change something starts a workflow. Each step has a risk class. Reads and quotes always run on their own. For the steps that change something, the Owner decides in advance, with a policy, how much an agent may do without asking, and the rest waits for a person. Term | Means | Provider | A business's MCP server that an agent can act on, such as a restaurant's booking server. The Owner registers it; agents find it with search_providers. | Workflow | An ordered list of tool calls on one provider, each with a risk class, such as check availability, hold a table, confirm the booking. A step can name the call that undoes it. | Policy | The Owner's standing permission for one agent and one workflow: which risks it may request, the largest amount, and when the permission expires. | Run | One execution of a workflow by an agent. It keeps every step's arguments and result. | ## Classes of action Risk | Means | Without a policy | Under a policy | read | Looks something up; changes nothing | Runs | Runs | quote | Asks the provider what something would cost; reserves nothing | Runs | Runs | reserve | Holds capacity that a later call can confirm | Runs, and is never repeated after an unclear outcome | Runs, and is never repeated after an unclear outcome | create | Makes a record that did not exist | Waits for the Owner | Runs on its own only if the Owner switched off Still ask me before every run, and the amount is within the policy's cap | pay | Moves money or credit | Waits for the Owner | Same rule as create. Agent payments also need a payment mandate | cancel | Removes or releases something live | Waits for the Owner | Same rule as create | Three rules hold whatever the policy says. A tool on the blocked list is refused before a run exists. A tool on the irreversible list, such as a refund, always waits for the Owner. And an agent can never approve, extend or widen its own run. ## Worked example: a restaurant booking A restaurant registers its booking server as a provider and defines the workflow `book_table`. The Owner writes one policy for the agent `api:kbk_ab12cd34`: risks read, quote, reserve and create, a largest amount of $50, 30 days, and Still ask me before every run switched off. A refund tool is on the irreversible list of a second workflow, `refund_booking`, because a run that contains an irreversible tool waits for the Owner from its first step. The amount is the deposit the booking takes, in cents: the agent passes `amount_credits`, and the Owner enters the cap in dollars. The `book_table` run: Step | Tool | Risk | What happens | 1 | check_availability | read | Runs at once and returns the open times. | 2 | hold_table | reserve | Runs at once. The table is held, not booked. | 3 | confirm_booking | create | Runs at once for a $20 deposit. A $120 deposit is over the $50 cap, so the run stops as pending_approval and the Owner is alerted. | A separate `refund_booking` run, whose `refund_deposit` step is a `cancel` on the irreversible list, is held for the Owner as soon as it starts, whatever the amount. The agent starts it, then polls for the result. Nothing in this request is a secret, and the agent never sees the restaurant's own credentials. ```sh curl -X POST https://www.knotbind.com/api/v1/actions/workflows/start \ -H "authorization: Bearer $KNOTBIND_API_KEY" \ -H 'content-type: application/json' \ -d '{ "workflow_id": "book_table", "provider_id": "bistro-nord", "inputs": { "date": "2026-11-14", "time": "19:30", "party": 4 }, "amount_credits": 2000, "reasoning": { "confirm": "Guest asked for Saturday at 19:30 for four." } }' ``` ```json { "id": "action_8f2c1d4e9a7b", "workflowId": "book_table", "providerId": "bistro-nord", "status": "completed", "currentStep": 3, "approval": { "required": false } } ``` With `"amount_credits": 12000` (a $120 deposit) the same request returns `"status": "pending_approval"`. The agent polls `GET /api/v1/actions/runs/{id}` until the status changes. See the Agent API (https://docs.knotbind.com/docs/agent-api#approvals) for the statuses and polling interval. ## How a request runs - An agent asks `POST /api/v1/actions/workflows/start` or the MCP tool `start_action_workflow`, with the workflow, provider and inputs. An agent may start 30 runs a minute. - Policy decides first A step whose tool is blocked, or that the policy does not allow, is refused before a run exists, so there is nothing to approve later. A credential-shaped value in the inputs stops the call (`sensitive_data_blocked`) and is recorded so you can rotate it. - A person releases what the policy does not cover A run that includes a step the policy does not cover waits as `pending_approval`. The Owner, never the agent and not a teammate, releases it from the dashboard. An alert named An agent action waits for approval is sent on every channel and cannot be switched off. The run page shows the exact resolved call before release. - Steps keep their record Each step is stored with its arguments and result before the next starts. A step that ends without a verifiable answer stops the run for a person: Knotbind never repeats a write it cannot prove did or did not happen. ## Policy reference Setting | What it does | Agent and capability | One agent, one workflow name. | Risks | Which risk classes the agent may request. | Largest amount | In dollars. A run whose amount_credits (cents) is above this waits for the Owner, even when the checkbox is off. | Still ask me before every run | On, every create, pay and cancel waits. Off, they run within the cap. | Allowed tools | When the list is not empty, any other tool is refused. | Blocked tools | Refused always. Wins over everything else. | Irreversible tools | Always wait for the Owner, even under a permissive policy. | Valid for | 1 to 365 days. A policy that expired grants nothing. | ## Stop and reverse An Owner can stop every agent action in the workspace with one switch. Reads, Checks and your own API keep working, and resuming is a person's choice. A finished run can be reversed only if every write step recorded an undo: the reversal is a new run, undo calls in the opposite order, and it waits for approval like anything else. Half-undoable runs are refused, naming the steps that cannot be undone. ## What this does not do - Retry a write that ended unknown, ever. - Let an agent approve, extend or widen its own request. - Simulate a write in a sandbox before approval. The preview shows what would be sent, and sending is still gated by you. - Delegate approvals to anyone but the Owner. ## Delegate operations, not upstream secrets. Source: [Credential vault](https://docs.knotbind.com/docs/credential-vault) Business Owners store encrypted credentials and authorize exact operations for verified API-key or OAuth-client identities. ## Operation-bound credentials Open Credentials (https://www.knotbind.com/dashboard/credentials) as an Owner. Supply a public HTTPS API base, OpenAPI JSON contract, explicit operation names and Bearer, API-key-header, Basic, OAuth client-credentials or OAuth browser/PKCE configuration. Secrets are sealed, never shown again. Rotation changes the credential version and revokes all derived grants. Deletion, disconnect and grant revocation remain available after downgrade. ## Provider browser connection ### What you configure - The provider's authorization URL and token URL. - The client ID and the exact scopes. - One authentication method: public with no secret, `client_secret_post`, or `client_secret_basic`. - The callback URL shown in the dashboard, registered at the provider. - An exact issuer, if you set one. The `iss` in the response must match it. ### How a person connects - Connect shows a link to the provider. The person signs in, consents, and completes 2FA there. - Knotbind never collects the provider password or the 2FA code. - The sign-in state lasts 10 minutes, uses S256 PKCE, and is bound to the member who started it and to the credential version. - That state is used once, in a committed transaction, before the token exchange. - The connection pages and the callback are not cached, and they do not leak the address in a referrer. ### How tokens are kept and refreshed - Access tokens and refresh tokens stay sealed. Knotbind never hands them out. - Before a call, an expiring access token is refreshed under an exclusive lock on the account. Two instances cannot rotate the same refresh token. - A successful refresh does not extend Owner consent and does not add scopes. - If the refresh fails, the material is missing, or the response is invalid, Knotbind clears the tokens and the grants. Connect again. - Connecting again invalidates the old operation grants. The Owner approves the new consent. No API call is replayed on its own. - If the provider omits an access lifetime, Knotbind uses one hour. It never keeps an access token longer than 24 hours. ## Explicit consent and expiry ### What the Owner grants - A workspace API key, or an OAuth client and member that already consented, with `tool:execute`. - The exact operation names, for 15 to 60 minutes. - For a write, a separate Owner approval and `tool:execute:write`. ### When the grant ends - An OAuth grant is tied to the client ID and the member ID. Refreshing the token does not extend the consent. - The grant cannot outlive the credential. - Knotbind stores only the hash of the execution token. When the consent expires, the Owner grants it again. ### What a granted call cannot send - The stored upstream credential. - A control character. - A reserved header. - A path segment of `.` or `..`. A hosted write still pauses for the one-time Owner approval on OpenAPI to MCP (https://docs.knotbind.com/docs/openapi-to-mcp). Vault consent does not skip that pause. ## Vend and execute ```sh curl -X POST https://www.knotbind.com/api/v1/vault/grants/GRANT_ID/token -H "Authorization: Bearer $AGENT_CREDENTIAL" curl -X POST https://www.knotbind.com/api/v1/vault/grants/GRANT_ID/execute -H "Authorization: Bearer $AGENT_CREDENTIAL" -H "X-Knotbind-Execution-Token: $EXECUTION_TOKEN" -H "Content-Type: application/json" -d '{"operation":"list_customers","arguments":{}}' ``` Both requests require the approved identity. Rotation revokes the old execution token without changing its deadline. The Gateway alias /v1/credential-grants/{id}/execute enforces the same checks. Calls validate arguments, never accept arbitrary URLs, use bounded guarded HTTP, and never retry. Known credential echoes are redacted. Audit logs record identity, credential ID, grant and attempted operation, never secrets or arguments. ## Safety boundaries ### Limits per workspace - 50 credentials. - 100 active grants. - 30 token rotations a minute. - 60 vault executions a minute. - 4 tool calls running at once, shared by every app instance on the same database. - 10 OAuth connection starts a minute, and 30 callbacks a minute. ### What a revoke does - A change to access and a call that is already running share one lock, so they cannot pass each other. - Revoking waits for a call that has already left. It does not pretend to cancel a write the provider has received. - If a worker dies holding a slot, that slot frees itself after 120 seconds. ### What this vault does not do - The in-memory adapter and the standalone packages keep their limits inside one process. - It does not return the provider's tokens. - It does not certify that a real assistant, or a production provider, accepted the connection. ## What an agent remembers between runs, and how it finds it again. Source: [Agent memory](https://docs.knotbind.com/docs/agent-memory) Agents store facts and notes in your workspace and recall them in a later session. Recall matches shared words by default; the Owner can also turn on recall by meaning, which is off until they do. ## What it does An agent calls `remember` to keep a fact, a preference or a working note, and `recall_memory` in a later session to find it again. Memory belongs to your workspace, is private to the agent that wrote it unless that agent shares it, and every write, read and delete appears in the audit trail with the agent's name. Kind | Written by | Use it for | `semantic` | The agent | Durable facts and preferences: “the deposit is 20 euros”. | `working` | The agent | Notes for the task in hand. | `episodic` | Knotbind | A record of a finished run, written when the run reaches a final state. An agent cannot write one. | ## The API Operation | Endpoint | Scope | Remember | `POST /api/v1/memory` | write | List what you can read | `GET /api/v1/memory` | read | Recall | `GET /api/v1/memory/recall?query=` | read | Forget one of your own | `DELETE /api/v1/memory/:id` | write | The same operations are MCP tools: `remember`, `recall_memory`, `list_memory` and `forget_memory`. ```sh # Keep a fact, visible to the other agents of this workspace curl -X POST https://www.knotbind.com/api/v1/memory \ -H "authorization: Bearer $KNOTBIND_API_KEY" \ -H 'content-type: application/json' \ -d '{"text":"Kitchen shuts at ten every Sunday evening.", "tags":["venue"],"visibility":"workspace"}' # Find it later curl "https://www.knotbind.com/api/v1/memory/recall?query=closing%20time&limit=5" \ -H "authorization: Bearer $KNOTBIND_API_KEY" ``` ```json { "results": [ { "id": "mem_…", "kind": "semantic", "text": "Kitchen shuts at ten every Sunday evening.", "tags": ["venue"], "agent": "api:kbk_Zq3x", "shared": true, "run_id": null, "created_at": "2026-11-03T10:00:00.000Z" } ] } ``` ## Who can read what - A memory is private to the agent that wrote it. Set `visibility: "workspace"` to share it with the other agents of the same workspace. - No agent can read another workspace's memory, and an agent can delete only its own. A delete of someone else's memory returns `404 memory_not_found`, the same as one that does not exist. - The Owner can clear every memory in the workspace from the dashboard (Actions, Agent memory). That is audited too. ## How recall finds things ### Shared words (always on) Recall scores the memories an agent may read by the words they share with the question: whole-word hits first, then partial hits, then tags, with newer memories winning ties. Common English words such as “at” and “the” are ignored. It needs no outside service. It only finds a memory that shares words with the question, and it looks at the 500 newest readable memories. When nothing matches, the answer says so, together with how the question was searched. An agent reading that note is meant to ask or verify, not to answer confidently from no memory. ### By meaning (paid plans, opt in, per workspace) Available on Pro and Business. A question like “when do you stop serving food at the weekend” finds “Kitchen shuts at ten every Sunday evening”, although they share no words. It reaches all of a workspace's memories, not only the 500 newest. It is off until your Owner turns it on Recall by meaning sends the text of your memories, and each question an agent asks, to Google's embedding service. Knotbind never switches it on for you. It is included in Pro and Business; the Owner turns it on in the dashboard under Actions, Agent memory, and can turn it off at any time. On Free, memory stays on shared words only. ### What is and is not sent What | Detail | Sent to Google, when it is on | The text and tags of a memory, once, when it is stored or indexed; and the text of a question, when an agent recalls. | Never sent | Anything that looks like a password, key or token, in a memory or in a question. Such a memory stays findable by shared words only. | Kept in the index | A numeric fingerprint of each memory, its id, its tags, its kind and who may read it. Never the memory text. The text stays in your workspace's database. | Who may read a result | Decided by Knotbind's database, not by the index. A result the agent is not allowed to read is dropped before it is returned. | ### If the service is unreachable Recall does not fail. It answers by shared words, the memory is still stored, and the dashboard shows Using keywords until the service is back. After repeated failures Knotbind stops calling the service for a minute so a slow provider cannot slow every recall. ### Turning it on and off - Turn on (Owner only): new memories are indexed as agents write them. Memories written earlier are found by shared words until the Owner presses Index existing memory, which sends their text to Google once and can be repeated safely: it only indexes what is missing. - Turn off (Owner only): nothing more is sent, and the workspace's index entries are removed. Your memories are not touched. - Who turned it on or off, and when, is recorded in the audit trail. ## Limits Limit | Value | Text per memory | 4,000 characters | Tags per memory | 12, up to 60 characters each | Results per recall | 1 to 10 (default 5) | Memories kept per agent and kind | 50. Past that, the oldest are folded into one record tagged `compressed` that keeps every source id. The fold joins the texts; it is not a model summary. | ## How fast it is Measured on a developer machine with the real services, not a promise for your deployment. - Searching the index takes under a millisecond and stays that way from 500 to 20,000 memories. Scanning every memory by words took about 110 ms at 20,000. - Recall by meaning is not faster on a first question: turning the question into a fingerprint is a call to Google that took about 270 ms. A question asked again is answered from a cache in a few milliseconds. The gain is finding memories by meaning and not slowing down as memory grows. ## Connect Knotbind to an assistant. Source: [MCP & OAuth](https://docs.knotbind.com/docs/mcp) Knotbind is a Streamable HTTP MCP server with OAuth 2.1, PKCE and dynamic client registration. Assistants can sign in without a pasted API key. ## OAuth flow - 401 challenge A protected tool call returns `WWW-Authenticate` pointing to protected-resource metadata. - Discover The client reads `/.well-known/oauth-protected-resource/mcp` and `/.well-known/oauth-authorization-server`. - Register It posts redirect URIs and a client name to `/oauth/register`. Public clients use no client secret. - Authorize Knotbind shows the workspace, app, redirect host and scopes. Owners can grant write; Members get read. - Use PKCE S256 exchanges a one-time code for a one-hour access token and rotating refresh token. ## Manual Claude setup ```sh MCP URL: https://www.knotbind.com/mcp Authentication: No sign-in if using a kbk_ API key Authentication: Sign in when needed for OAuth Transport: Streamable HTTP ``` ## Relay detection Create a relay from the dashboard or `POST /api/v1/relay`. Add the returned URL to an assistant: ```sh https://www.knotbind.com/relay// ``` If the assistant can set a header, leave the token out of the URL. Every proxy between the assistant and Knotbind records a URL in its access log, and it does not record a header value: ```sh POST https://www.knotbind.com/relay/ X-Knotbind-Relay-Token: ``` An assistant whose connector form takes only a URL needs the first form. Both forms use the same token, and rotating it stops both. The assistant sends its MCP requests to the relay. Knotbind forwards them to your configured MCP server and passes the responses back. On `initialize`, the client reports its `clientInfo.name` and version. Knotbind uses that reported name to show a likely client profile as connected. Treat the URL as a credential Anyone with the relay URL can use it to reach your MCP server. Only the client name and version are stored for connection detection; tool arguments and results are not stored by that detection feature. Rotating the relay invalidates the old URL immediately, so update the URL in every assistant using it. ## Know which agent link broke and where. Source: [Alerts and monitors](https://docs.knotbind.com/docs/alerts) Configure actionable alerts, recurring readiness checks, OpenAPI drift monitoring and Owner-approved plan requests. ## Set up customer alerts Open Settings (https://www.knotbind.com/dashboard/settings) in the customer dashboard. Configure email, a Slack incoming webhook, and/or a signed HTTPS webhook. Alert content names affected assistants, the failing layer and endpoint/tool, available evidence, and concrete recheck steps. ## Monitor readiness and API changes Readiness checks run weekly on Free, daily on Pro and every six hours on Business. A score drop above the configured threshold or a failing regression sends an alert. OpenAPI drift uses the stored normalized description as a Baseline. Breaking changes alert once per fingerprint. When a Check's answer changes shape on purpose, the Owner accepts the new shape from the Run on the dashboard, and the button appears only when the call succeeded and only the shape differs: accepting an outage would hide it. ## MCP tool drift and server health Each MCP server in your registry is polled on its own schedule, and every tool schema is fingerprinted. A change that breaks callers — a tool removed, a required parameter added, a parameter type changed — opens a Finding and sends an alert naming the tool and what changed. A change that does not break callers, such as an added optional parameter, is recorded without an alert. Each server also carries its own status. A server that fails a poll is degraded; one that fails three polls in a row is offline and alerts the Owner once. When it answers again the alert is cleared, so a later outage is reported once more rather than being swallowed. See MCP servers (https://docs.knotbind.com/docs/mcp-servers) for the whole model. ## Verify webhook signatures Generic webhook requests carry `X-Knotbind-Signature: t=,v1=`, the event and delivery IDs. The hex is HMAC-SHA256 over the exact raw request body prefixed with `t.`. Reject stale timestamps (over five minutes), parse the raw body only after signature verification, and compare MACs in constant time. The secret is shown once when created or rotated. ## When an agent action waits for you An agent can request a create, pay or cancel action. Unless the Owner's policy covers it, only a person releases it. When a run starts waiting — at creation, or at a later step after a release — Knotbind sends an An agent action waits for approval alert on email, Slack and webhook, with a link straight to the run. This alert cannot be switched off: a waiting run does not move on its own, and an unlisted approval is a stalled agent. The run page shows what releasing sends: the exact tool and the exact arguments, resolved, before anything runs. If a finished run's steps recorded an undo, the Owner can request a reversal: a new run, in the opposite order, that waits for approval like any other action. A run whose steps did not record an undo is refused, with the tool named, because undoing half a sequence invents a state nobody chose. ## Plan approval An agent can use `POST /api/v1/billing/plan-request` or the MCP tool `request_plan_change`. The Owner gets the request on Billing and can approve to open Stripe Checkout or decline. This does not automatically charge or change a plan. ## One-time customer API actions Use `POST /api/v1/tools/call` or MCP tool `call_tool_once` to call a connected customer's MCP tool exactly once and get its result. Write-capable tools require explicit `allow_write: true` consent; this call does not become a scheduled Check. Knotbind's Stripe Checkout is only for a Knotbind subscription. Customer orders and payment links must be created by the customer's own API/MCP tool. See the Agent API (https://docs.knotbind.com/docs/agent-api) for the calls and errors. ## Watch every MCP server you run. Source: [MCP servers](https://docs.knotbind.com/docs/mcp-servers) Knotbind keeps a registry of your MCP servers. Each one is polled on its own schedule, its tools are fingerprinted, and a change nobody announced opens a Finding instead of breaking your assistants quietly. The registry ## Several servers. One view of which ones are broken. An Account can hold more than one MCP server: production and staging, a partner's server and your own. Each one keeps its own tools, its own schema history, its own health, and its own Findings. Discover→Fingerprint→Check→Baseline→Finding ## Add a server Open MCP tools (https://www.knotbind.com/dashboard/tools) in the dashboard and add a server by name and URL, or use the API. The first poll discovers the server's tools and stores their schemas. ```sh POST /api/v1/integration {"mcp_url": "https://api.example.com/mcp"} ``` ## Credentials A server can be open, use a bearer token, send an API key in a header you name, or require OAuth. A token you paste is encrypted with the application secret and never shown again — not on the page, not in a log, not in the Audit Record. If a deployment prefers to manage its own secrets, give the name of an environment variable instead and Knotbind reads the value from the process. Method | What Knotbind sends | None | Nothing | Bearer token | Authorization: Bearer <token> | API key | The header you name, default x-api-key | OAuth 2.1 | Authorization: Bearer <access token>, renewed when it expires | ## Knotbind as an OAuth client Some MCP servers delegate to a user's own account and need OAuth rather than a pasted token. Knotbind speaks that role too, in the opposite direction from the one on the MCP and OAuth (https://docs.knotbind.com/docs/mcp) page: there, an assistant signs in to Knotbind; here, the Owner signs their server in to Knotbind. - Discover Knotbind reads the server's protected-resource metadata, then the authorization server's metadata, falling back from RFC 8414 to OpenID Connect discovery. - Authorize The Owner is sent to the authorization server. The request carries PKCE and the RFC 8707 `resource` parameter, so the token is issued for this server and no other. - Exchange The one-time code is exchanged for an access token and a refresh token. The access token is sealed with the application secret; the refresh token is stored beside it and renews the access token when it expires. ## Contract Checks For every tool Knotbind discovers, it suggests a Check built from that tool's own declared schemas: the arguments it takes, and the shape it promises to return. A suggestion is not a Check. The Owner reviews each one and approves it before it runs on a schedule, and a tool that can change data is never scheduled without that approval. Read-only suggestions can be approved in one step with Approve all read-only; it takes only the servers that themselves say a tool only reads, up to the plan's Check limit, and leaves everything else waiting for a person. ## Baselines The first time an approved Check passes, Knotbind records the shape of the answer. A later answer with a different shape fails the Check: a field that appeared, or disappeared, is a change that somebody should look at. When the change was intended, the Owner accepts the new shape as the new Baseline, and that decision is written to the Audit Record under their name. A Baseline is about the answer, not the request A declared output schema says what the tool promises. A Baseline says what it actually returned last time. The first is the contract; the second is the evidence that the contract still holds. ## Workflow Checks A single tool call is often only half the story. A Workflow Check calls one tool after another, so a later step can use what an earlier step returned — the customer id from a search, the order from a lookup. ```sh [{"serverId":"mcp_1","toolName":"search_customers","parameters":{"email":"test@example.com"},"extractOutputAs":"customer"}, {"serverId":"mcp_1","toolName":"get_orders","parameters":{"customerId":"{{customer.id}}"}}] ``` Each step can assert the shape it expects, and every step records its own duration and evidence. A failed step stops the workflow unless it says otherwise. ## Reading the tool badges Each tool is marked read-only when the server itself declares it so, unconfirmed · 70% when only its name sounds like a read, or may write (with its own score) when the name says it changes data. The percentage is a fixed rule, not a guess from a model, and it exists because names lie: a tool called `get_or_create_customer` reads its name's mind and writes yours. Only the server's own word lets anything run unattended. ## Drift, Findings and health Every tool schema is fingerprinted. When a schema changes, Knotbind compares it against the fingerprint it recorded last time and decides whether the change breaks anyone: a new required parameter, a changed type, or a removed tool breaks callers; an added optional parameter does not. Change | What happens | Tool removed | Breaking. Opens a Finding. | Required parameter added | Breaking. Opens a Finding. | Parameter type changed | Breaking. Opens a Finding. | Optional parameter added | Not breaking. Recorded, no Finding. | Description changed | Not breaking. Recorded, no Finding. | A breaking change opens a Finding in the Reliability Loop and notifies the Owner by email, Slack or webhook — once per change, not once per poll. Each server also carries its own status: healthy, degraded while it is failing, or offline once it has failed three polls in a row. The Owner hears about an outage once, and hears about it again if the server comes back and later fails again. The server card keeps the evidence: when it was last checked, how long the last successful check took and which transport answered it (`JSON` or `SSE`), and how many of its last 20 checks passed. A failed check records no duration, because a timeout is not a latency. ## OpenAPI from your tools Knotbind can describe a registered server's tools as an OpenAPI 3.1 document, so tools that are meant for agents can also be read by OpenAPI tooling, code generators and linters. Each tool becomes one operation. A tool that can write is marked as needing approval. That mark is not the hosted pause. A hosted OpenAPI write waits for the one-time Owner approval described on OpenAPI to MCP (https://docs.knotbind.com/docs/openapi-to-mcp). ```sh GET /dashboard/mcp-servers/{id}/openapi.json ``` ## From a failed call to an approved fix. Source: [Reliability](https://docs.knotbind.com/docs/reliability) Knotbind is a control plane, not an API editor. Your implementation stays in your repository; Knotbind checks it, explains failures and waits for approval. Check→Detect→Diagnose→Propose→Approve→Resolve ## What gets repaired, where, and by whom "Fix" means different things in different parts of Knotbind. Read this before the rest of the page. Step | What changes | Where | Who | Approve a repair | Knotbind's own Check, so it matches the API as it is now. | Inside Knotbind | The Owner approves. Your API and repository are not touched. | Deploy approved proposal (Business plan) | The approved change is sent on. | Your deployment webhook, or one pull request in your repository | You review and merge. With neither configured, the button is a dry run. | MCP server repair | Source edits that rename a field everywhere it is used, with your tests run first. | A draft pull request through Mend, when a repository is marked as the server's repo | You review and merge. | Fixing the API itself | Not done by Knotbind. | Your own code | You, or your team. | ## A realistic drift case An orders tool used to return `user_id`. A release renames it to `account_id` and nobody announces it. The agent's call still succeeds, which is why this kind of change is hard to see. The Baseline recorded what the answer looked like the last time it passed, so the Check fails on the shape, not on the status: ```sh Check: get_order Request: MCP tools/call get_order {"id":"1042"} Expected: HTTP 200, output matches the Baseline Observed: HTTP 200, field 'user_id' is missing, 'account_id' is new Reason: response does not match the expected shape Finding: opened after the second consecutive failure ``` The Owner can accept the new shape on purpose, which records `account_id` as the new Baseline, or fix the server. The same loop covers a removed tool, a new required parameter, a changed parameter type and a slower answer. The sandbox below uses a simpler break so you can see every step in two minutes. ## Demo scenario In the Demo Sandbox, click Change API contract. The demo then refuses `GET /customers/1` with HTTP 422 until the request includes a `region` query value. The value is any region the demo API asks for. It is not the country of the customer, and it is not where Knotbind is hosted. Run Checks twice. One failure marks the Check as suspect. The second consecutive failure opens a Finding. ## How a repair is drafted After a Check fails, choose Draft + verify fix. Knotbind reads the failed response and proposes one request change. For this demo failure, the proposal adds `?region=eu`. That value is only a sample that makes the demo Check pass. Credentials are not part of the draft. Knotbind keeps the draft only if the same Check passes in the Sandbox. A draft that does not pass is discarded. The Owner still approves a kept draft before it changes the Check. ## What happens after you approve Approval changes Knotbind's Check, not your API and not your repository. The approved request replaces the failing one, the Audit Record names who approved it, and the next scheduled Run calls the new request. When that Run passes, the Finding closes. Nothing is deployed by approving. GitHub is not required for any of this. Connect a repository only when you want an approved fix written back into your own code. On the Business plan, Deploy approved proposal does one of two things: - With a deployment webhook configured, Knotbind posts the approved change to your pipeline. Your pipeline decides what to do with it. - With a GitHub repository configured, Knotbind also opens one pull request containing the change. You review and merge it. See Build & handoff (https://docs.knotbind.com/docs/build). With neither configured, the button is a dry run and changes nothing. The whole repair loop works without a GitHub account. ## Demo versus Customer Sandbox The Demo Sandbox is a real, deterministic in-process HTTP test server used for demos, onboarding and tests. Its controls change the server behavior for the current Customer: contract drift returns HTTP 422 until a `region` query value is supplied, outage returns HTTP 503, Restore returns normal responses, and Reset restores the Baseline and reconfigures Checks. It is not a visual-only mockup, but it is intentionally a small simulation rather than a production backend. For real testing, choose Connected staging API during onboarding. Knotbind runs Checks against the Customer's public HTTPS Sandbox through the guarded Runner, enforcing public destination checks, same-origin paths, GET/POST-only methods, timeouts and response limits. MCP Integrations call the Customer's MCP server through the MCP Invoker instead of the Demo Sandbox. See the complete Sandbox reference (https://docs.knotbind.com/docs/sandbox). ```sh Check: getCustomer Request: GET /customers/1 Expected: HTTP 200 Observed: HTTP 422 Reason: field 'region' is required Proposal: GET /customers/1?region=eu ``` ## What an MCP Check looks like An MCP Check calls a tool rather than an endpoint, so the evidence looks different but the loop is the same. The tool's own declared schemas become the contract, and the shape of the answer becomes the Baseline. ```sh Check: get_customer Request: MCP tools/call get_customer {"id":"1"} Expected: HTTP 200, output matches the declared schema Observed: HTTP 200, 'name' is missing Reason: response does not match the expected shape Finding: opened ``` A tool that changes shape without saying so fails the same way, because the Baseline records what the answer looked like the last time it passed. See MCP servers (https://docs.knotbind.com/docs/mcp-servers). When the Owner approves a repair for an MCP Check, and the workspace has marked a repo as its MCP server repo, Mend opens a draft pull request there with real source edits: it finds the handler for that tool, renames the field everywhere it is used, runs your tests, and only then proposes the change. See Mend for your MCP server. ## What is persisted Record | Contains | Run | Checks, status, latency, response preview and trigger | Finding | Failure evidence, diagnosis and state | Repair Proposal | Before/after change and Sandbox result | Audit Record | Actor, action, time and sanitized detail | Production boundary No API key, OAuth token or MCP tool can approve, reject or deploy a production Repair Proposal. That action belongs to the Owner in the dashboard. A secret is never a record MCP credentials are encrypted before they are stored and are never written to a Run, a Finding, an Audit Record or a page. The Audit Record names the method, not the value. ## Two ways to test a Check before it reaches customers. Source: [Sandbox](https://docs.knotbind.com/docs/sandbox) The Demo Sandbox is Knotbind's own small test server. A connected staging API is yours. Checks run against one of the two, and neither one is your production system. ## Demo Sandbox The Demo Sandbox is a real HTTP server that Knotbind runs for demos, onboarding and tests. It is not a picture of a server. Its controls change how it answers, and they change it only for your account. Another customer's Demo Sandbox is unaffected. In normal mode it answers one request: ```json GET /customers/1 200 { "id": "1", "name": "Example Customer" } ``` The dashboard controls do the following: Control | What changes | Change API contract | GET /customers/1 starts requiring a region query value and returns HTTP 422 until the Check sends one. The sample repair uses region=eu. | Simulate outage | Every request returns HTTP 503. | Restore | Responses go back to normal. | Reset | Responses go back to normal, and the Reliability loop is set up again with the current Checks. | A normal demonstration runs in this order: - Run a Check and see it pass. - Choose Change API contract. - Run Checks again and read the failed evidence and the Finding. - Choose Restore or Reset. - Run Checks again and see the recovery. It is a simulation The Demo Sandbox is deliberately small. It does not hold your data, and it does not stand in for your application. It also does not simulate payments, orders, sign-in failures, rate limits, slow responses or partial failures. ## Connected staging API During onboarding, choose Connected staging API and give a public HTTPS address. Knotbind resolves each Check against that address. A Check for `GET /customers/1` against `https://staging.example.com/api` calls: ```sh https://staging.example.com/api/customers/1 ``` A connected staging API is called under these limits: - HTTPS only, to a public address. - The address is checked again at request time, so it cannot be switched to a private network after you save it. - A Check path stays on that same address. It cannot point at another host. - Only GET and POST are sent. - A request stops after 10 seconds. - The response is capped in size. - Redirects are not followed. ## MCP servers An MCP integration does not use the Demo Sandbox or the staging address. Knotbind calls the MCP server you registered, sends the initialization handshake, and then calls the tool named by the Check. If that server needs a credential, either paste it, in which case it is encrypted before it is stored and never shown again, or give the name of an environment variable, in which case Knotbind reads the value when it calls the server and does not store it on the account. See MCP servers (https://docs.knotbind.com/docs/mcp-servers#credentials). See how a failed Check becomes a fix (https://docs.knotbind.com/docs/reliability), or how an MCP server is watched (https://docs.knotbind.com/docs/mcp-servers). ## Register and authenticate your MCP server. Source: [Guide: Connect an MCP server](https://docs.knotbind.com/docs/guide-connecting-mcp-server) Step-by-step guide to connecting your MCP server to Knotbind, choosing the right authentication method, and verifying the connection works. ## Add your server Open MCP tools in your dashboard. The Add MCP server card takes four things. Only an Owner can add a server. - Name A label for the server (for example `Production API` or `Staging MCP`). Each name can be used once in your workspace. - URL The full address where your server answers, for example `https://api.example.com/mcp`. It must start with `https://`, use the standard port 443, and have no username or password in it. The address, and every address its name resolves to, must be public, so private and local addresses are refused. For a server on your own machine, use a tunnel that gives it a public https address on port 443. - Authentication How Knotbind signs in: None, Bearer token or API key header. OAuth is set up afterwards, see below. - Credential The token or key, if the method needs one. It is encrypted when it is saved and is never shown again. Adding a server does not contact it. The server starts as pending until you press Discover tools on its card. ## Choose how Knotbind signs in ### Bearer token Use this when your server expects an `Authorization` header with a fixed token. ```sh Authorization: Bearer eyJhbGciOiJIUzI1NiIs... ``` Choose Bearer token and paste the token as the credential. Knotbind sends it with each request to that server. Credentials are write-only A saved credential is encrypted and is never shown back, in the page or in logs. To change it, save a new one on the server card, or press Remove credential. ### API key header Use this when your server expects a key in a header of its own, such as `X-API-Key`. ```sh X-API-Key: sk_live_51H... ``` Choose API key header. When you save the credential on the server card, give the exact header name as well as the key. ### OAuth Use this when your server follows the MCP authorization standard. You do not enter endpoints, a client id or scopes. Add the server with None, then press Connect with OAuth on its card. Knotbind reads the server's published authorization details, sends you to its sign-in page, and stores the result when you approve. This works only if the server publishes its OAuth Protected Resource Metadata. If it does not, you will see "That server does not offer OAuth, so Knotbind cannot connect to it." Knotbind connects as a public client with PKCE and no client secret. ### An environment reference If the credential is kept in an environment variable on the Knotbind side rather than pasted in, fill in the environment-reference field with the variable's name instead of a credential. It is treated as a bearer token. ## Check that it works - Press Discover tools On the server card, press Discover tools. Knotbind connects, asks the server for its tools, and records each one. You see "Tools discovered from your MCP server." - Read the status The card shows connected in green once discovery works, with the tools listed under it. The card also shows when the server was last checked and its Response time, how long the last successful check took. A failed check clears the response time, since a failed call only tells you it timed out. Each tool carries one of three markers: - read-only: your server says the tool only reads. This is the only marker Knotbind trusts. - unconfirmed: the tool's name sounds like a read (for example `list_orders`) but your server does not say so. A name can hide a write, as in `get_or_create_customer`, so Knotbind does not treat it as read-only. - may write: the tool looks like it changes data. To get read-only, have your server set the `readOnlyHint` annotation on tools that only read. - Run a test workflow Create a one-step workflow to confirm a tool call works end to end. See Writing workflow checks. Suggested Checks After discovery, Knotbind suggests one Check for each tool. A Check calls the tool on every scheduled Run and fails if the answer does not match what the tool declares. Nothing runs until you approve it. Your plan sets how many Checks can be active at once (Free 3, Pro 10, Business 25, across all your servers), so on a server with many tools approve the ones agents depend on most; the other suggestions stay suggestions. Press Approve on a suggestion to approve it alone. Open its Arguments first: Knotbind fills them with example values. Press Approve all read-only to approve every suggestion whose tool your server marks read-only. The button shows how many it will approve. Tools marked unconfirmed or may write are never included, so review those one at a time. Approval stops at your plan's Check limit. The suggestions left over stay on the page, and Knotbind tells you some were left. Each approved Check is recorded in the Audit Record under your name. Troubleshooting "Enter a public https URL for your MCP server." The URL did not start with https://, uses a port other than 443, has a username or password in it, or points at a private or local address. Use a public https address on the standard port. "The MCP server did not answer." Discovery could not complete. The server card shows the error text. After one or two failures the server shows disconnected, and after three in a row it shows error. Check the URL and that the server is running, then press Discover tools again. If the card's error mentions authorization, check the credential: Bearer token: the token may have expired or been revoked. Save a new one. API key header: the header name must match exactly, including capitals. OAuth: press Connect with OAuth again. The earlier approval may have expired. It connected but no tools appear The server answered, but its tool list is empty. Check that your tools/list handler returns at least one tool. "An MCP server with that name already exists." Names are unique within your workspace. Pick a different name, or remove the old server first. Next steps Write your first workflow check Understand how Baselines detect changes Learn about the MCP server registry (https://docs.knotbind.com/docs/guide-writing-workflow-checks) - Let Mend fix your MCP server code when an API breaks it ## Create multi-step MCP workflows with assertions. Source: [Guide: Write workflow checks](https://docs.knotbind.com/docs/guide-writing-workflow-checks) Learn how to design workflow checks that call multiple MCP tools, reference results from earlier steps, and validate responses with JSON Schema assertions. ## What is a workflow check? A workflow check is a sequence of MCP tool calls that validates your server behaves correctly end-to-end. Each step calls one tool, and later steps can reference data from earlier responses. Example scenario: Search for a customer by email, then fetch that customer's orders using the id the first call returned. ## Create your first workflow Register your server and press Discover tools on its card first. Then open MCP tools in your dashboard, find the Workflow checks panel, and fill in the form: - Name A label shown on the workflow card and in alerts (for example `Customer order flow`). - Steps (JSON) A JSON array with one object per step, in the order they run. Press Save workflow when it is ready. ## Describe a step Each step needs a `serverId` and a `toolName`: - `serverId`: the id of the registered server the tool lives on, shown as Server id on its card. One workflow can use more than one server. - `toolName`: the tool, exactly as the server advertises it. - `parameters`: the input object passed to the tool. It can use `{{'{{'}}name.field{{'}}'}}` to refer to an earlier result. - `extractOutputAs` (optional): the name this step's result is stored under, for later steps to use. - `assertOutput` (optional): a JSON Schema the result must match. The step fails if it does not. - `stopOnFailure` (optional): set to `false` to keep going after this step fails. The default is to stop. ```json [ { "serverId": "mcp_1", "toolName": "search_customers", "parameters": { "email": "alice@example.com" }, "extractOutputAs": "customer", "assertOutput": { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" } } } }, { "serverId": "mcp_1", "toolName": "list_orders", "parameters": { "customer_id": "{{customer.id}}" } } ] ``` ## Reference earlier results Use `{{'{{'}}stepName.path{{'}}'}}` to inject values from a previous step's result into a later step's arguments. ### Example workflow Step 1: Create a customer ```json Tool: create_customer Arguments: { "name": "Alice", "email": "alice@example.com" } Expected result (schema): { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" } } } ``` Step 2: Retrieve the customer by ID ```json Tool: get_customer Arguments: { "id": "{{create_customer.id}}" } Expected result (schema): { "type": "object", "required": ["name", "email"], "properties": { "name": { "const": "Alice" }, "email": { "type": "string", "format": "email" } } } ``` The `{{'{{'}}create_customer.id{{'}}'}}` reference pulls the `id` field from Step 1's result and injects it into Step 2's arguments. Nested paths You can reference nested fields with dot notation: {{customer.address.city}}. Arrays are accessed by index: {{orders.0.total}}. ## Write assertions with JSON Schema The Expected result field uses JSON Schema Draft 2020-12. This lets you validate structure, types, required fields, and value constraints. Common patterns Require specific fields ```json { "type": "object", "required": ["id", "status"], "properties": { "id": { "type": "string" }, "status": { "enum": ["active", "pending"] } } } ``` Validate array length ```json { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "required": ["name"] } } ``` Check a field matches a pattern ```json { "type": "object", "properties": { "email": { "type": "string", "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" } } } ``` Require an exact value ```json { "type": "object", "properties": { "version": { "const": "2.0" } } } ``` When a workflow runs Run once Press Run once on a workflow card to run it now. The card then shows the time, how it ran, and each step with its duration and the reason if it failed. Only the latest result is kept. On a schedule A saved workflow also runs on its own, with the MCP monitor. It uses the same schedule as tool-change checking: weekly on Free, daily on Pro, every 6 hours on Business. Turn the monitor on. In Settings, tick Monitor MCP tool drift. Without it nothing runs on its own, and the workflow card says so. Run once always works. Switch one workflow off. Press Switch off on its card to stop it running on schedule without deleting it. Stop on first failure By default a workflow stops at the first step that fails (a tool error, a schema mismatch, or a tool that cannot be called). Later steps are skipped, which prevents cascading failures when a step needs an earlier result. Set stopOnFailure to false on a step to keep going. Read-only tools only A workflow calls only tools that the server marks read-only right now. A step is refused if its tool is not read-only, so a workflow never changes your data. To call a tool that changes data, use the one-time tool console, where you approve each call yourself. When a tool changes If a tool a workflow calls has changed since you last pressed Discover tools (a new schema, or even a new description), the workflow is not run. Its card shows needs review and says why. Press Discover tools on that server's card to record the tool as it is now, then press Run once. When a workflow fails Once a workflow has run more than once, its card also says how many of its last 20 runs passed, and whether each run was scheduled or started by hand. A scheduled workflow that fails, or is not run because a tool changed, sends one A saved MCP workflow fails alert. It does not repeat while the workflow stays broken, and it alerts again after the workflow has passed and then fails. You can turn this alert off in Settings. A failed workflow does not open a Finding. Troubleshooting Step fails: the tool reported an error The tool answered with an error. The usual causes are a missing required field, a value of the wrong type, or a {{'{{'}}reference{{'}}'}} that points to a field the earlier step did not return. Check the tool's input schema on its card. Step fails: the output does not match the assertion The tool returned a result, but it did not match your assertOutput schema. The card names the field or constraint that failed. Either update the schema to match what the tool really returns, or fix the tool if the result is wrong. A reference is not resolved A {{'{{'}}name.field{{'}}'}} reference was not replaced. Check that the name matches an extractOutputAs on an earlier step, that the field exists in that step's result, and that the earlier step passed, because a failed step stores nothing. Best practices Start simple: Test one tool at a time before chaining several steps. Name results clearly: Use extractOutputAs names such as customer or order, not result1. Validate structure, not exact values: Assertions should focus on "type", "required", and "enum" rather than brittle "const" checks on dynamic data. Keep workflows focused: One workflow per feature or user journey. Run once before you rely on the schedule. Catch a bad parameter or assertion early. Next steps Learn how baselines catch regressions Configure alerts (https://json-schema.org/draft/2020-12/json-schema-validation) ## Understand baselines and drift detection. Source: [Guide: What a baseline is](https://docs.knotbind.com/docs/guide-what-baseline-is) Learn how Knotbind captures response baselines, detects structural drift, and helps you distinguish breaking changes from safe API evolution. ## What is a baseline? A Baseline is the shape of a Check's answer, recorded the first time that Check passes. Knotbind keeps the fields, their types and how they nest, and not the values. A field such as `"id": "cust_12345"` is kept as `"id": string`. On every later Run, the Check's answer is compared with its Baseline. If the shape is different, the Check fails, even when the call itself returned what the Check expected. ## Why Baselines matter An assistant that relies on a field breaks when that field disappears or changes type. A Baseline notices that on the next Run, instead of an assistant finding out in production. ## How a Baseline is captured - The first passing Run The first time a Check passes, Knotbind records the shape of its answer as that Check's Baseline. Each Check has its own. - Shape, not values Only the structure is kept: which fields exist, their types (`string`, `number`, `array`) and nesting. A different id or timestamp on its own does not fail the Check. Workflow steps do not have Baselines A Baseline belongs to a Check. The steps of a saved workflow check their own assertions, and a tool's input schema is watched for drift separately. ## What counts as a change A Baseline is strict. Any difference in shape fails the Check: - A field is missing that was in the Baseline - A field is new, one that was not in the Baseline. This fails the Check too, even though adding a field is usually safe for an assistant. - A field has a different type, for example a string that is now a number A Baseline does not tell a safe change from a breaking one. It tells you that the answer changed, and you decide. ## What happens when the shape changes - The Check fails. The Run is marked failed, and the result says which field differs. - After two failing Runs in a row, a Finding opens. One failure is not yet a Finding, so a single flaky call does not wake you. You get an alert when the Finding opens. - You decide what the change is. It was either intended or it is a bug. See below. ## When you meant to change the answer If the change was planned, accept it as the new Baseline. Open Dashboard, find the failed Run in the Runs table, open the failed Check, and press Accept as new Baseline. - The Baseline becomes the answer the Check just returned, and the Audit Record notes who accepted it. - The button appears only when the call returned what the Check expected and the shape is what changed. If the call failed outright (an error status, no response), it is not offered, because accepting that would hide a real outage. - It appears on the latest Run only, and only for the Owner. Do it before a Finding opens Accepting at the first failure means the next Run passes and no Finding opens. If a Finding is already open, accepting makes the Check pass again, but the Finding stays open until you close it through the Finding's own actions (diagnose, repair and approve, or dismiss). You cannot undo it Accepting replaces the old Baseline. The Audit Record keeps the fact that you did it, but not the old shape, so be sure the change is intended before you accept. ## Baselines and declared schemas A Check can also carry a declared schema, for example a tool's published `outputSchema`. The two are different: | Baseline | Declared schema | Who defines it | Knotbind, from the first passing Run | You, or the tool's own output schema | What it checks | The answer has exactly the shape it had | The answer fits the schema, extra fields allowed | A new field | Fails the Check | Passes, unless the schema forbids it | How you resolve it | Accept as new Baseline, or fix the API | Fix the API, or change the schema | ## Common scenarios ### You added a new field The Check fails, because the Baseline did not have that field. If you meant it, accept the new Baseline. Assistants that ignore the new field are not affected. ### You renamed a field The old name is missing and a new one appeared, so the Check fails. This one can break assistants that used the old name. Accept the new Baseline only when the assistants have been told. ### A field changed from string to number Type changes break clients that expect a type. Either revert the change, or accept it and let assistant owners know. ### A field is sometimes missing The Check fails on the runs where the field is absent. If the field should always be there, fix the API. If the answer legitimately varies in shape, a Baseline is the wrong tool for that Check, because it compares the whole shape every time. ### The Check fails on every Run A different id, timestamp or other value does not fail a Baseline, since only the shape is compared. If it fails every time, the shape itself is changing between calls. Read the result to see which field differs. ## Best practices - Accept early. If the change is intended, accept it at the first failure so no Finding opens. - Write breaking changes down. When you accept a new Baseline after a rename or a type change, add it to your API changelog so assistant developers know. - Use a declared schema for what must never change. Required fields and types you promise belong in a schema, which keeps failing when they break. - Test before you deploy. Run your Checks against a staging copy before an API change reaches production. ## Next steps - Learn the full reliability loop from detection to fix Configure alerts (https://docs.knotbind.com/docs/reliability) ## Give an agent access without handing out keys. Source: [Guide: MCP authentication](https://docs.knotbind.com/docs/guide-mcp-auth) How to connect an MCP server so a credential stays a secret, an OAuth token stays short and bound, and nothing that writes runs without a person. ## Store it as a secret, not a copy A token you paste into Knotbind is encrypted with the application secret and never shown again — not on a page, not in a log, not in the Audit Record. If your deployment keeps its own secrets, name the environment variable instead of pasting, and Knotbind reads the value from the process. Either way, treat the stored credential like a password: rotating it means saving a new one and revoking the old one at the provider. ## Prefer OAuth over a pasted token When your server supports the MCP authorization spec, press Connect with OAuth instead of pasting. Knotbind acts as a public client with PKCE and no client secret: it discovers the server's authorization details from its published metadata, and sends the RFC 8707 `resource` parameter, so the token it receives is valid for that server and nowhere else. The access token and refresh token are then sealed like any other credential. A token bound to one resource is worth less stolen than a universal key. ## Publish only what an agent should touch Annotate honestly. The read-only hint is what lets Knotbind schedule a Check or bulk-approve a suggestion for a tool; a tool marked read-only that actually writes gets run unattended and the damage is yours to explain. Tools that change data stay human-gated: a one-time call needs the Owner's consent for that exact call, and an agent-requested create, pay or cancel waits for a person unless the Owner's policy covers it. See Governing agent write actions (https://docs.knotbind.com/docs/write-actions). ## The address itself is checked Knotbind refuses to reach private or internal addresses on your behalf: https on port 443 only, no credentials in the URL, and every address the hostname resolves to must be public. The check runs again at connect time, so a DNS record that answers publicly and then points inward is refused as well. Timeouts and response sizes are bounded, so a server that hangs cannot hold Knotbind's poll open forever. What this gives your side: an MCP URL you hand Knotbind cannot become a way to reach your metadata service or intranet. ## Rotate deliberately - Server credential: save the new value on the server card; it replaces the old sealed one. Revoke at the provider too — Knotbind cannot un-leak a token. - A relay URL for your own MCP server: treat it as a credential; rotating invalidates the old URL immediately, so update every assistant using it. - An OAuth grant: reconnect to issue a new consent; revoking at the authorization server takes effect on the next call attempt. ## Model traffic is a different door Everything above is about Knotbind calling your MCP server. Your assistants' model calls go through the Gateway and the credential vault, where an execution grant is short, operation-bound and consented by the Owner: see the credential vault (https://docs.knotbind.com/docs/credential-vault). ## Verify what you are sent Knotbind's webhooks are signed: check the HMAC and reject stale timestamps before trusting an alert's content, as described on Alerts and monitors (https://docs.knotbind.com/docs/alerts). An alert that looks like Knotbind's but fails verification is not Knotbind's. ## Generate and host MCP tools from OpenAPI. Source: [OpenAPI to MCP](https://docs.knotbind.com/docs/openapi-to-mcp) Use the existing Build dashboard or local CLI. No separate gateway service is required. ## Preview, download, deploy Owners with Business Build access can open Build / OpenAPI to MCP. Upload JSON, paste a document, or supply a public HTTPS specification URL. Preview saves a draft without making upstream API calls. Download either JSON tool schemas or a standalone TypeScript stdio server package. The package runs on Node 22.19+ without dependency installation and uses environment credentials; saved upstream secrets are never exported. tools.ts names the argument type for each selected tool. The server still executes from server.ts and config.json. Private GitHub repository After tools are generated, download the server and commit it in the repository you connected in Mend (https://www.knotbind.com/dashboard/build/openapi). Mend is the one place Knotbind connects to GitHub. This page does not ask for a GitHub token, and it does not open a pull request. Tool names use snake_case. Select names with a comma-separated filter. Read-only operations are selected by default; exposing write tools requires explicit opt-in. Calls to write tools may mutate real data and are never automatically retried. ## Hosted endpoint Set a public HTTPS API base URL and optional Bearer, API key header, Basic or OAuth client-credentials configuration. OAuth requires an explicit token URL, client ID, client secret and optional scopes. Credentials are encrypted at rest; access tokens are exchanged for each call and never persisted. Confirm deployment to replace the workspace relay target and revoke its previous URL. Copy the private URL shown once, then add it to your MCP client. Stop and revoke the endpoint from the same page. The hosted relay supports initialize, tools/list, tools/call, ping, and initialized notifications. Existing monitoring configurations are preserved separately. Confirm a Sandbox target at deployment to enroll read-only tools that accept empty arguments, subject to the shared workspace Check limit. Checks run now and on the existing account watch; the first successful response captures each Check's independent Baseline. Writes and tools needing explicit arguments are skipped. ## Scoped execution grants Create an agent API key with `tool:execute` on the API access page. The Owner can authorize exact deployed tool names for 15 to 60 minutes. The scoped relay URL must be used with that same API key in Authorization. Writes require both explicit Owner approval and `tool:execute:write`. That grant is not the per-call pause below. Revoking the key or grant, expiry, stopping or redeploying invalidates access. `POST /api/v1/credential-grants/{id}/token` rotates an approved agent's token without extending its deadline or exposing an upstream credential. This is API-key-bound delegation, not verification of an assistant's self-reported clientInfo. ## Approve one write call A hosted relay write does not run until the Owner approves that exact call. Read-only tools are not paused. The upstream API is not called while the call is waiting. A downloaded package does not have this pause: the process that runs it owns the call. - Call `tools/call` on the hosted relay URL with the write tool and the arguments to run. - Knotbind answers HTTP 403 and JSON-RPC `-32001`. The message says the write is waiting for Owner approval. The error data carries `approvalId`, a one-time `approvalToken`, and `expiresAt`. Keep the token. Knotbind stores only its hash. - Open Build / OpenAPI to MCP as the Owner. Under "Write tool calls waiting for one-time approval", choose Approve this call once for that tool. The approval lasts 15 minutes from the paused call, not from the click. Retry the same tools/call with the same tool and the same arguments. Send the token in the X-Knotbind-Tool-Approval header. Knotbind then calls the upstream API once. ```sh curl -X POST "$RELAY_URL" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create_item","arguments":{"title":"Lamp"}}}' curl -X POST "$RELAY_URL" -H "Content-Type: application/json" -H "X-Knotbind-Tool-Approval: $APPROVAL_TOKEN" -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"create_item","arguments":{"title":"Lamp"}}}' ``` A second use of the token, a changed argument, another tool, or an expired approval does not match. Retrying without a match pauses a new call and returns a new token. At most 20 unused approvals are kept. Arguments larger than 16 KB are refused before a token is issued. What a tool call cannot send These checks run before the upstream request, on the hosted relay and on a generated server. A failed check throws. It does not become an upstream call. CheckWhat is refused Upstream credentialAn argument that contains the stored upstream credential. Control charactersA path, query, header, or nested body string containing an ASCII control character. Reserved headerA tool argument named Authorization, Cookie, Host, Content-Length, Connection, Transfer-Encoding, or Proxy-Authorization. Path segmentA path argument whose value is a single dot or a double dot. The credential belongs in the hosted authentication configuration or in KNOTBIND_UPSTREAM_CREDENTIAL on a downloaded server, not in tool arguments. If an upstream error echoes that credential, Knotbind replaces the known value with [REDACTED] before returning the body. Local CLI ```sh node bin/knotbind.mjs openapi-to-mcp ./openapi.json --ops list_users,get_user --max 100 node bin/knotbind.mjs openapi-to-mcp https://api.example.com/openapi.json ``` No API key is needed for local conversion. Use - as the input for stdin. --max bounds top-level array responses, not the operation count. Use --format package --out server.tar.gz for a runnable package; writes require --allow-write. Extract and run npm start. Set KNOTBIND_API_BASE_URL to override the API base and KNOTBIND_UPSTREAM_CREDENTIAL for configured authentication. OAuth exports accept a caller-supplied short-lived Bearer token, never the hosted client secret. Supported scope and limits Standalone HTTP transport The exported package also supports stateless Streamable HTTP: set KNOTBIND_MCP_TRANSPORT=http, optional KNOTBIND_MCP_PORT (default 3000), and a separate random KNOTBIND_MCP_TOKEN with 32+ printable non-space characters. It binds only to 127.0.0.1 at /mcp. POST requests require that Bearer token, JSON content type and Accept for both application/json and text/event-stream. Responses are JSON; notifications return 202. GET/DELETE return 405 because no server stream or sessions are provided. HTTP requests are capped at 1 MB, 60/minute and four concurrent requests per process. Remote hosting needs an explicitly secured TLS reverse proxy; untrusted Host/Origin values are rejected, and cross-origin browser access is not supported. The inbound MCP token is never the upstream credential. This is local transport verification, not real-assistant acceptance or a production hosting certificate. Owners can supply explicit validated read-only Sandbox fixtures, inspect account-scoped current/prior Run history and enable failure/recovery alerts. Review spec update regenerates a draft from supplied JSON without changing the live endpoint, adding unselected tools or publishing a repository PR. The separate credential vault (https://www.knotbind.com/dashboard/build/openapi) supports OAuth-client/member operation consent. ### Scheduled contract review Remote contract watch tracks one public HTTPS JSON source on the existing durable Account schedule, at an Owner-selected 1-168 hour interval. Polls are bounded to 500 KB/ten seconds, send no upstream auth and follow no redirects. Changes create a separate review record; no operation, deployment, credential grant or Baseline is changed. New operations remain unselected, read-to-write transitions block staging, and an unrelated Owner draft cannot be overwritten. Dismissal is scoped to source/baseline fingerprints; downgrade pauses fetching. Manual checks are capped at six an hour. A change in the order of keys alone does not count as drift. ### Repository dry-run bundle Owners can stage a current safe review as a draft or download selected contract/tools plus SHA-256 file hashes and proposed repository branch/PR metadata. Paths must be relative JSON files under contracts/; GitHub/GitLab URLs and refs are validated. Blocked reviews contain metadata only. This adapter never writes files, calls a repository, creates a branch, commits or publishes a PR. Sandbox verification and actual publication require separate explicit authorization. Conversion uses bounded schema expansion and a 2 MB normalized tool limit; review file contents are capped at 5 MB. Treat schema/descriptions as confidential even though saved upstream auth is excluded. Area | Limit | Specification | OpenAPI 3.0/3.1 JSON, 500 KB, up to 100 selected operations | Schemas | Local references; recursive and external references rejected | Requests | Scalar path/query/header arguments and JSON object bodies | Hosting | 60 requests/minute and 4 active account tool slots shared by PostgreSQL-backed app instances | Network | Public HTTPS only for upstream API; bounded response, timeout, no redirects | Not included | YAML, multipart, upstream streaming, interactive OAuth/2FA, raw secret vending, certified production hosting, automatic repair or real-assistant certification | Keep relay URLs private The URL is a bearer credential. It is not a verified agent identity. Rotate or stop it when access must be revoked. Multi-instance deployments need a shared ingress limit for a fleet-wide quota. ## Deliver an API and MCP server the customer owns. Source: [Build & handoff](https://docs.knotbind.com/docs/build) Build work happens in the customer's repository and infrastructure. The dashboard records the handoff, staging URL, acceptance checklist and monitoring connection. ## Handoff package Artifact | Purpose | API source | Customer-owned implementation | MCP server | One Streamable HTTP endpoint for assistants | OpenAPI document | Machine-readable REST contract | Docker / CI files | Customer's deployment pipeline | Checks | Expected capabilities and responses | Rollback notes | How to return to the previous version | ## Acceptance path - An Owner downloads the generated server from OpenAPI to MCP (https://docs.knotbind.com/docs/openapi-to-mcp) and commits it in the repository connected in Mend. That records the repository and marks the source delivered. It does not deploy the server or start monitoring. - Customer deploys to staging. - Knotbind runs tool discovery and a Baseline. - Customer tests capabilities in the real assistants. - Owner accepts the handoff and monitoring starts. The server-side handoff publisher uses `KNOTBIND_GITHUB_TOKEN`, or a GitHub App when that token is empty (`KNOTBIND_GITHUB_APP_ID`, `KNOTBIND_GITHUB_APP_INSTALLATION_ID`, and `KNOTBIND_GITHUB_APP_PRIVATE_KEY`). The App key stays in the process environment. A repair pull request opens in the customer's repository through Mend, not here. A failed pull request does not undo the deployment. See Build service Request a Build ## Keep your code in step with the APIs it calls. Source: [Mend](https://docs.knotbind.com/docs/mend) Mend watches the APIs your TypeScript or Python code calls and opens draft pull requests when a change would break it. On every plan. It never writes to your default branch. ## Two ways to try it Way | What you do | What you see | The demo | Open www.knotbind.com/demo, enter your email (a Slack webhook is optional) and open the link Knotbind emails you. Press the Mend button. | A made-up provider, Acme, removes a field. Mend shows the lines of a small sample app that used it, the fix, and a real draft pull request on a public sample repository. It stays open for 24 hours. | Your own repo | On any plan, connect GitHub, pick a repo and tick the APIs it calls. Free includes 1 repo, Pro up to 5, Business up to 20. | When one of those APIs changes in a way that breaks your code, a draft pull request with the fix, or an issue when Mend is not sure. | ## Which APIs Mend watches Mend needs an API's published description (its OpenAPI file) to know what changed. Today it watches the GitHub REST API, the OpenAI API, the Stripe API and the core Twilio API, read every hour. An API company can also register and send its own description (see For API providers below). Acme, used in the demo, is not a real company. It exists only so the demo has something to break. ## Connect a repo - Open Mend, Repos as the workspace Owner and choose Connect GitHub. GitHub asks which repos to share with the Knotbind Mend app. Pick a repo. Suggest APIs reads its package.json, requirements.txt and pyproject.toml for official SDKs (openai, octokit, stripe, twilio) and ticks the matching APIs. Check them against what the code calls, then add the repo. Mend assumes your code matches each API's current version and acts on later changes. Free includes 1 repo, Pro up to 5 and Business up to 20. Each plan also lets you add APIs of your own: 1 on Free, up to 3 on Pro and up to 10 on Business. What Mend does when an API changes StepWhat happens TrackMend reads each API's published description on a schedule and compares versions field by field. DetectIt finds the files and lines in your repo that use what changed: the call, the type, every read of the field. ExplainEach change gets a plain explanation and a severity (low, medium, high, critical) from fixed rules. A model may only write the wording and raise severity by one level. FixA removed field the provider says was renamed is renamed in your code. Anything else is listed under Needs a person. VerifyYour repo's own install, build and tests run on the patched code in a throwaway container. Install has network access, with dependency scripts off for npm and only prebuilt wheels allowed for pip. Build and tests have no network. OpenA draft pull request on a knotbind/mend/ branch, with the diff, severity, confidence and the test result. Pull request or issue Every fix has a confidence from 0 to 100%. A pull request opens only when your tests pass and confidence is at least 70%. Otherwise Mend opens an issue that says why and shows the patch. Comment /mend open-pr on the issue, or use the button in the dashboard, and Mend opens it as a draft with the reason on it. You need write access to the repo. What lowers confidence A request matched by path or SDK name rather than a verified API URL takes 15 points off. Changes that still need a person take 30 off. Failing tests cap it at 25. New fields When an API adds a response field, Mend can declare it as an optional property on the type your repo already uses for that response. It is off by default. Turn on New fields for a repo in the dashboard, or set adopt: true in .knotbind.yml. These pull requests are separate from fixes, on their own branch, and cannot break existing code. Mend for your MCP server If you run an MCP server so AI assistants can call your API, and you have connected the repo that holds it, Mend can fix that code too. When a Reliability Check finds that a tool stopped working because a field was renamed upstream, Mend downloads your MCP server repo, finds the handler for that tool, renames the field everywhere it is used (the type, every read, every construction), runs your tests, and opens a draft pull request with the source edits. This works for TypeScript servers written against the official MCP SDK (server.tool(name, schema, handler)). When the finder cannot point at exactly one handler, or your tests fail, Mend opens a repair note instead: a file that shows the verified change and tells you where to apply it. Mark your MCP server repo once: open Mend, Repos (https://www.knotbind.com/dashboard/mend/repos), find the repo and press MCP server repo: yes. Only one repo per workspace can be marked this way. The repair runs automatically when a Check breaks; you do not need to ask for it. ## Opt out To | Do this | Pause a repo | Pause in the dashboard, or enabled: false in .knotbind.yml. | Skip one change | Dismiss it in Changes, or list it under ignore in .knotbind.yml. | Dismiss a pull request | Close it. Mend will not reopen those changes. | Undo a merge | The fix is one commit: git revert the merge commit. | Stop completely | Remove the repo, or uninstall the app on GitHub. | ```sh mend: enabled: true adopt: false ignore: - openai # every change from a provider - openai:system # one field - github:GET /repos/{owner}/{repo} # one operation ``` A `.knotbind.yml` that cannot be read stops Mend for the repo until it is fixed. ## What Mend reads and sends - It reads only TypeScript and Python source files and your dependency manifests (`package.json`, `requirements.txt`, `pyproject.toml`). It does not parse or read environment files. Python code is parsed as text and never run by Mend itself. - Access to your repo uses a short-lived token that GitHub issues to the app for the repos you chose. Nothing is stored. - No file name, path or code is sent to a language model. Only the provider's side of a change is. - Every detection, patch, test run, pull request and issue is written to your Audit Record. ## Providers Mend tracks the GitHub REST API, the OpenAI API, the Stripe API and the core Twilio API (messages, calls and accounts). Calls are matched by URL (`fetch`, `axios`-style, `{ url }`) for all of them. For GitHub, OpenAI and Stripe, calls are also matched by the official SDK's method names (`openai`, `octokit`, `@octokit/rest`, `stripe`), in files that import the SDK, and only when the call starts at the client: `stripe.customers.list()` is Stripe's, while `db.customers.list()` in the same file is not. A client counts when it is built from the SDK, passed in with the SDK's type, or held in a field of that type. For Stripe this covers the v1 API, which is the one Mend tracks, and not `stripe.v2.*`. For Twilio and the APIs you add yourself, calls through the npm SDK's methods are not found yet, because that SDK's naming has not been checked against the real package. Other Git hosts are not supported yet. ## Python Mend reads Python repos the same way it reads TypeScript ones. It finds calls made with `requests`, `httpx`, `aiohttp` and `urllib`, including a client built with a `base_url`, a URL assembled with an f-string, `+`, `.format()`, `%` or `urljoin`, and a base URL kept in a constant. It also finds calls through the official `openai`, `stripe` (the `StripeClient` and the older `stripe.Customer` classes) and `twilio` packages. Those names were checked against the real packages. Calls through `PyGithub` are not matched by method name yet; calls to the GitHub API's URL are. Mend follows a response into the shape your code reads it as: a `TypedDict`, a `@dataclass`, a pydantic `BaseModel` or a `NamedTuple`, through an annotation, `cast`, a constructor or `model_validate`. Every declaration, `["field"]`, `.get("field")`, attribute read, keyword argument and dict literal that uses the field on that type is found. Mend does not run a type checker, so a value whose type the code never states is reported as a request but its field uses are not edited. For a fix, a removed field the provider renamed is renamed everywhere. With New fields on, a new field is declared as `NotRequired[...]` on a `TypedDict` or `Optional[...] = None` on a dataclass or model. Mend writes `X | None` only when your repo says it needs Python 3.10 or later, because that spelling fails when the module loads on older versions. The tests run in a `python:3.12` container. Mend installs your `requirements.txt` or `pyproject.toml` dependencies and `pytest` with the network on, allowing prebuilt wheels only, so a package that has to be built from source fails the install instead of running its build script. A requirement that is a local path, a git URL or an editable install is refused for the same reason, and Mend opens an issue that says so instead of a pull request. Then Mend byte-compiles the code and runs `pytest` with no network. Repos that use Poetry, Pipenv, PDM or uv without a `requirements.txt` are not supported yet. ## An API of your own On the Mend overview, choose Add an API that is not listed and give a name and the https address of the API's OpenAPI 3.0 or 3.1 description (JSON, or simple YAML). Mend reads it every hour, treats the first read as the baseline, and acts on later changes. Only the workspace Owner can add one, only your workspace can see it, and your plan sets how many: 1 on Free, 3 on Pro and 10 on Business, or a number agreed in writing. If your plan goes down, Mend keeps watching the ones you have and you cannot add more until you are under the number. The address must be public: Mend refuses private and internal addresses, non-https addresses, addresses with a username or password, and any redirect that leads to one. If the description lists no `servers`, Mend treats the address it was read from as the API's host. ## For API providers A provider can register with Knotbind and push its API description and migration notes when it ships a version, so its customers get fix pull requests the same day. Contact us (https://www.knotbind.com/contact?service=mend) to register. You get a key; it is shown once. ```sh curl -X POST https://www.knotbind.com/mend/provider/versions \ -H "authorization: Bearer $KNOTBIND_PROVIDER_KEY" \ -H "content-type: application/json" \ -d '{"version":"2.0.0","openapi":{...},"notes":[{"field":"phone","replacedBy":"phone_number","message":"Use phone_number."}]}' ``` `openapi` is an OpenAPI 3 object, or JSON or YAML text. A note names a removed response field and optionally the field that replaces it. The replacement counts only if it exists in the new description with the same type. Up to 30 versions an hour. ```sh curl https://www.knotbind.com/mend/provider/adoption \ -H "authorization: Bearer $KNOTBIND_PROVIDER_KEY" ``` Adoption is counts only: repos tracking your API and pull requests opened, merged and closed per version. A number is shown only when at least 5 repos stand behind it. You never see a workspace, a repo name, a file or any code. See Mend (https://www.knotbind.com/mend) Open Mend ## See whether an Apify run supports a reliable agent integration. Source: [Apify evidence](https://docs.knotbind.com/docs/apify) Knotbind observes bounded Actor/Task run metadata while keeping contract and workflow Checks separate. ## What it does Configure an Apify Actor and Task in the customer dashboard. The Demo evidence button lets you preview the Reliability Report without an Apify account. A connected configuration reads the latest Task Run through Apify's read-only API and stores bounded status, IDs, duration, Dataset ID and field metadata. ## What it does not claim An Apify Actor run succeeding means the Actor completed. It does not prove that an MCP tool schema, response contract or downstream agent workflow still works. Knotbind correlates external evidence with its own Checks, Runs, tool-definition fingerprints and Findings. To use it, open Apify in the customer dashboard. To see what it produces without an Apify account, use the Demo evidence button. ## Test your MCP server with Meta Muse. Source: [Meta Muse](https://docs.knotbind.com/docs/muse) Meta's Muse Connector Platform accepts API and MCP connectors. Knotbind can test your server contract and record a real Muse connection through the relay; it does not submit or claim directory approval for you. ## What we verified Meta's Muse Connector guidelines describe a connector submission and review process, API/MCP support, tool permission classification, business verification, privacy and data-processing review, credentials and test-user information. This is separate from adding a custom connector in the Muse app. ## Try a custom connector - Open the Muse app's Connectors settings Choose to create a Custom Connector and use the Streamable HTTP MCP URL from your Knotbind MCP Tools page. - Choose authentication Use OAuth if the MCP server requires a user sign-in. Select no sign-in only for a deliberately public endpoint. A public endpoint lets anyone who has its URL call its public tools. - Test a read-only tool Ask Muse to list the tools, then call a harmless read-only tool and compare the answer with the source service. - Record the actual result In Knotbind → Assistants → Meta Muse, choose Yes or No and write what you observed. A Knotbind contract Check alone does not count as a real Muse test. ## Before directory submission Prepare | What reviewers need | Business | Verified organization details and proof of authority to publish. | Privacy and data | Privacy policy, data-processing answers, retention, deletion and security practices. | Connector | Public HTTPS endpoint, authentication method, scopes, tested tools and accurate read/write/sensitive-write classifications. | Review access | Dedicated test account, sample data and a walkthrough for each tool. | Operational quality | Complete task flows, confirmed versus pending results, safe retries, support contacts and incident response. | Submission status Knotbind does not submit this connector to Meta on your behalf, and this guide does not claim it has been approved or listed. Submissions are made by the connector owner in Meta's Muse Connector Platform. Read Meta's Muse connector guidelines ## Paid add-ons that extend the Knotbind Gateway. Source: [Gateway modules overview](https://docs.knotbind.com/docs/plugins) Gateway modules are paid, per-workspace add-ons you configure from the Knotbind dashboard. Each one extends what your managed Gateway does with every request that passes through your access key. ## What modules do Each module is a paid add-on. Semantic Cache is applied on your Gateway. Content Guardrails and Request Analytics run in Knotbind. Model Failover and Advanced Rate Limits add rules and quotas for your access keys. You turn a module on from the dashboard. A rule or quota is added on the Gateway page and takes effect without a restart. ## Module catalog Module | Price | Applies to | Description | Semantic Cache | $19/mo | Chat and completion responses | Cache LLM responses by exact match or semantic similarity. Cut cost and latency for repeated or similar prompts. | Content Guardrails | $19/mo | JSON chat responses | Replaces email addresses, US phone numbers, US Social Security numbers and payment card numbers in message and reasoning text. | Request Analytics | $15/mo | Recent requests | Groups this workspace's recent requests by provider and model on the Gateway page. | Model Failover | $29/mo | One access key | Adds a fallback model list for one access key. Enabling it creates no rule. | Advanced Rate Limits | $12/mo | One access key | Adds a requests-per-minute quota for one access key, on top of the key's own limit. | ## Pricing Each module adds a fixed monthly fee to your Pro or Business subscription. Your base plan already includes the Knotbind Gateway itself; modules are optional add-ons. Enable or disable a module at any time — the change takes effect immediately, and the next invoice reflects it. ## What is available now Module | State | Semantic Cache | Available. Configure it on Gateway modules. | Content Guardrails | Available. Knotbind redacts four patterns in JSON chat message and reasoning text. | Model Failover | Available. Enable it, then add a fallback rule on the Gateway page. | Advanced Rate Limits | Available. Enable it, then add a requests-per-minute quota on the Gateway page. | Request Analytics | Available. The Gateway page groups recent requests by provider and model. | A module that is enabled but has no rule or quota yet is marked Not configured on the Gateway page. Content Guardrails covers four patterns only. For anything else, contact us. Enabling a module Open Gateway → Gateway modules as an Owner. Each module shows its price and state. Enable it there. Semantic Cache is configured on that page. Fallback rules and extra quotas are added on the Gateway (https://www.knotbind.com/contact?service=gateway) page after the module is enabled. The Gateway page reports whether the module is running, not configured, or in error. ## How configuration reaches your Gateway Knotbind owns the whole path. Your dashboard settings are validated server-side, applied to your Gateway, and stored against your workspace so they survive restarts. When a module is enabled, the `/v1` proxy also forwards that module's request headers — for Semantic Cache, the `x-knotbind-cache-key` header that names a cache entry. Headers belonging to a module you have not enabled are never forwarded. Module configuration is private to your workspace: another workspace cannot read or change it, and every enable, disable and configuration change is written to your Audit Record with the acting member. ## Evidence-based errors and explicitly approved examples. Source: [Gateway error hints](https://docs.knotbind.com/docs/gateway) Pro and Business Owners can opt in per key. Status and explicit validation fields guide correction; raw error inputs and credentials do not become examples. ## Enable hints per key Open Gateway (https://www.knotbind.com/dashboard/gateway) as an Owner and enable Agent-friendly errors on a workspace access key. Both native and engine proxy paths retain upstream status, use bounded structured validation fields and preserve successful/SSE responses. Errors are limited to 64 KB and ten seconds. No renamed field, endpoint or OAuth refresh URL is guessed; the Gateway does not retry. ## Approve trusted format examples In Trusted format examples, select a key, supply a bounded scalar JSON Schema and explicitly approve non-sensitive synthetic fixtures. This approval is separate from the hints toggle. Only exact fields identified by a 400/422 response receive expected constraints and your explicit example, labeled owner-approved-schema with a fingerprint. A zip_code error is never silently renamed to postal_code. Unknown/unapproved fields get no invented example. ```json { "type": "object", "properties": { "zip_code": { "type": "string", "pattern": "^[0-9]{5}$", "examples": [ "10115" ] }, "max_tokens": { "type": "integer", "minimum": 1, "examples": [ 128 ] } } } ``` This is a synthetic schema illustration, not proof that a particular provider accepts these fields. Approval checks every supplied example against the supported constraints. Limits: 32 KB, 100 scalar fields, four nested object levels, at most three examples per field. Supported types are string/integer/number/boolean/null, bounded enum/const, numeric/string bounds, limited anchored character-class patterns and email/UUID/date/UTC date-time formats. Sensitive credential fields, common credential-like values, arbitrary regex, references/composition and unsupported keywords are rejected. Email fixtures use reserved example domains. Owners must still ensure values contain no real secrets or personal data. ## Storage and privacy Approved schema fixtures persist privately per key with Owner/date/fingerprint, and can be removed after downgrade. Other workspaces cannot change them. Telemetry stores only the latest timestamp, status, field count, duration and Retry-After presence. Audits omit example values. Known credentials are filtered from enriched error fields/headers; no failing request value is used as a sample. Synthetic previews make no provider request. ## How this was tested Both Gateway paths were exercised over real HTTP against a synthetic provider, with identical approved schemas and only the hints toggle changed. The test client never retries authentication, rate-limit or unknown-outcome errors and never guesses an unknown field. The results are local timings and recovery counts. They are not a production SLA, a measured improvement for real assistants, or a customer metric. ## Cache LLM responses by exact match or semantic similarity. Source: [Semantic Cache](https://docs.knotbind.com/docs/plugin-semantic-cache) The Semantic Cache module routes repeated or semantically similar prompts through a cache layer on your Knotbind Gateway, reducing cost and latency for common queries. ## When to use it Enable Semantic Cache when your application issues many near-duplicate or closely related requests — FAQs, product lookups, classification prompts, documentation Q&A — where the exact answer is likely to repeat. The cache sits in front of your configured providers and applies to all keys in the workspace that have the module enabled. ## Configuration Setting | Description | Cache mode | Direct only (exact string match) or Direct + Semantic (embedding similarity). | TTL | How long cached responses are served. 30s, 5m (default), 10m, 30m, 1h, 6h, 24h. | Similarity threshold | For semantic mode: 0.5–0.99 (default 0.8). Higher = stricter match. | Cache by model | Include the model name in the cache key (recommended). | Cache by provider | Include the provider name in the cache key. | Embedding model | Required for semantic mode. Choose from supported providers (OpenAI text-embedding-3-small/large). | Dimension | Vector dimension for semantic comparison (1536 or 3072 for OpenAI). | Exclude system prompt | When checked, the system prompt is not included in the cache key. | Conversation history threshold | Number of prior messages to include in the cache key (1–50, default 3). | Default cache key | A fallback key when one is not supplied by the caller. | ## Using the cache key header By default the cache key is derived from the request body. To name an entry yourself, send an `x-knotbind-cache-key` header on your request to `/v1/chat/completions`. Requests that share a cache key can be served from the same entry. This header is only forwarded when Semantic Cache is enabled for your workspace; otherwise the Gateway ignores it. ```sh curl https://YOUR-SITE/v1/chat/completions \ -H "Authorization: Bearer kb_live_..." \ -H "content-type: application/json" \ -H "x-knotbind-cache-key: faq-returns-policy" \ -d '{"model":"groq/openai/gpt-oss-20b", "messages":[{"role":"user","content":"What is your return policy?"}]}' ``` Two things decide whether a request is cached at all: - A cache key must be present — either your `x-knotbind-cache-key` header or the Default cache key you set in the dashboard. Without one, the request goes straight to the provider. - The conversation must stay within the Conversation history threshold. Longer conversations are not cached, because their context makes a repeat answer unlikely. Direct matching runs first. Only when it misses does semantic similarity run, and only in Direct + Semantic mode. Writes are asynchronous: on a miss you get the provider's answer immediately and the entry is stored in the background, so a first request never waits on the cache. Entries survive a Gateway restart and expire on their TTL. ## Status in the dashboard Gateway → Gateway modules reports whether Semantic Cache is loaded and, if it could not be applied, a short reason. The operator Gateway dashboard shows each key's budget used and its request-rate cap. Request count, latency and spend are workspace totals on the Gateway (https://www.knotbind.com/dashboard/gateway/modules) page. ## Limits Setting | Range | TTL | 30s, 5m, 10m, 30m, 1h, 6h, 24h | Similarity threshold | 0.5–0.99 | Conversation history threshold | 1–50 messages | Embedding models | OpenAI text-embedding-3-small (1536), text-embedding-3-large (3072) | Semantic mode needs an embedding provider configured on your Gateway. Direct-only mode needs none, which makes it the cheapest way to start: exact repeats are served from cache with no embedding call at all. ## Redact four personal-data patterns in JSON chat responses. Source: [Content Guardrails](https://docs.knotbind.com/docs/plugin-guardrails) Content Guardrails replaces four personal-data patterns in JSON chat message and reasoning text. It does not scan requests, streamed responses, or secrets. Enable it from Gateway modules for $19/month. ## What it filters When the module is enabled, Knotbind rewrites the message text and the model's reasoning text in a successful JSON chat completion before it reaches the caller: - Email addresses, replaced with `[EMAIL]` - US phone numbers, replaced with `[PHONE]` - US Social Security numbers in ###-##-#### form, replaced with `[SSN]` - 16-digit payment card numbers, replaced with `[CARD]` Requests are not scanned. Streamed responses pass through unchanged. Redactions are not written to the request log. Postal codes, other national identifiers, API keys and tokens are not detected. ## Response shape Redaction happens in-memory on the `choices[].message.content` and `choices[].message.reasoning_content` fields of a JSON chat completion. The response structure is otherwise unchanged. Knotbind does not add an `X-Redacted` header or a redaction count. ```json { "id": "chatcmpl-123", "choices": [{ "message": { "role": "assistant", "content": "Call [EMAIL] or ship to 123 Main St." } }] } ``` ## How to enable Go to Gateway modules (https://www.knotbind.com/dashboard/gateway/modules), open Content Guardrails, and choose Enable. It applies to JSON chat responses for this workspace immediately. The Gateway (https://www.knotbind.com/dashboard/gateway) page shows it as Running once it is enabled. That label means Knotbind will redact matching text. It is not a count of redactions. ## Status in the dashboard Gateway → Gateway modules (https://www.knotbind.com/dashboard/gateway/modules) reports whether Content Guardrails is loaded. Redactions are not logged, and the Gateway (https://www.knotbind.com/dashboard/gateway) page does not show a redaction count. ## Limits Setting | Description | Patterns | Four fixed PII patterns: US email, US phone, US SSN, 16-digit card numbers | Response fields | Only content and reasoning_content in JSON chat completions | Requests | Not scanned — redaction is response-side only | Streams | Not rewritten — pass through unchanged | Logs | Redactions are not written to the request log | ## A fallback model list for one access key. Source: [Model Failover](https://docs.knotbind.com/docs/plugin-failover) Model Failover lets an Owner add an ordered list of fallback models for one access key. Enabling the module creates no rule until you add one. ## What it does Open Gateway modules and enable Model Failover. Then open Gateway (https://www.knotbind.com/dashboard/gateway/modules) and add a fallback rule: choose one access key and list one to five models, separated by commas. The rule is stored for that key only. Removing the rule, or disabling the module, deletes the rules that belong to this workspace. ## Response status Failover triggers on HTTP `502`, `503`, `504`, or a connection timeout. The Gateway tries each model in order until one returns a successful response. If all models fail, the last error is returned to the caller. ```sh https://YOUR-SITE/v1/chat/completions $ access key has failover: gpt-4o, gpt-4o-mini, claude-3-5-sonnet ``` The caller sees only the final response — no intermediate retries are exposed. A header `X-Failover-Attempts` reports how many models were tried. ## What it does not do - Create a fallback chain when you only enable the module. - Change another workspace's rules. - Retry a request whose outcome is unknown (e.g. a partial stream or an HTTP 200 with a content error). - Retry streamed responses mid-stream. - Apply to a key without an explicit fallback rule. ## Status in the dashboard Gateway → Gateway modules reports whether Model Failover is loaded. Each access key on the Gateway (https://www.knotbind.com/dashboard/gateway/modules) page shows its current failover model list, if any. ## Limits Setting | Description | Models per rule | 1–5, tried in order | Triggers | HTTP 502, 503, 504, connection timeout | Rules per workspace | One per access key | Streamed responses | Not retried mid-stream | Monthly fee | $29 per workspace | Per-key monthly budget and requests per minute are already set when you create an access key. Those do not require this module. ## One extra requests-per-minute quota per access key. Source: [Advanced Rate Limits](https://docs.knotbind.com/docs/plugin-rate-limits) Every access key can already carry a monthly budget and a requests-per-minute limit. This module adds one more requests-per-minute quota for a chosen key. ## What you have without it Open Gateway (https://www.knotbind.com/dashboard/gateway) as an Owner and create an access key with a monthly budget and a requests-per-minute cap. The customer Gateway page does not show the budget used or the rate cap. Those columns are on the operator Gateway dashboard. ## What the module adds Enable Advanced Rate Limits on Gateway modules (https://www.knotbind.com/dashboard/gateway/modules), then add a quota on the Gateway page. You choose one access key and a whole number from 1 to 100000 requests per minute. The quota applies to every model on that key. It does not add per-second, per-hour, per-model, or burst limits. Disabling the module removes the quotas that belong to this workspace. The monthly fee is $12. ## How it enforces The extra quota is stored as a per-minute request cap on that access key. Knotbind does not document the exact status, body or `Retry-After` value the Gateway returns when the cap is reached, so this page does not show a sample error. ## Status in the dashboard Gateway → Gateway modules (https://www.knotbind.com/dashboard/gateway/modules) reports whether Advanced Rate Limits is loaded. The extra quota list shows the access key and its requests-per-minute cap. It does not show how many requests remain in the current window. ## Limits Setting | Description | Requests per minute | 1 to 100,000 per access key | Rules per workspace | One per access key | Granularity | Per-minute cap; no per-second, per-hour or burst setting | Per-model limits | Not supported — quota applies to all models on the key | Monthly fee | $12 per workspace | ## Recent requests grouped by provider and model. Source: [Request Analytics](https://docs.knotbind.com/docs/plugin-analytics) Request Analytics groups this workspace's recent Gateway requests by provider and model on the Gateway page. It does not export metrics or extend log retention. ## What you have without it The operator Gateway dashboard shows each access key's monthly budget used and its request-rate cap. The customer Gateway page does not. Request count, success rate, latency, tokens and cost are workspace totals, not a per-key report. ## What the module adds Enable Request Analytics on Gateway modules (https://www.knotbind.com/dashboard/gateway/modules). The Gateway page then shows a table of recent requests grouped by provider and model: request count, average latency, tokens and cost. The rows are limited to this workspace's access keys and to the recent log window. Payloads are not included. The monthly fee is $15. ## What is logged The table groups recent requests by provider and model. Each row shows request count, average latency, total tokens and cost. It does not show the access key, HTTP status, separate input and output tokens, or cache hit and miss. Request bodies and responses are not stored. ## Status in the dashboard Gateway → Gateway modules (https://www.knotbind.com/dashboard/gateway/modules) reports whether Request Analytics is loaded. The Gateway (https://www.knotbind.com/dashboard/gateway) page shows the analytics table when the module is enabled. ## Limits Setting | Description | Retention | The latest 100 requests in this workspace | Grouping | By provider and model, per workspace | Payloads | Not stored — request and response bodies excluded | Export | Not available — view only in the dashboard | Monthly fee | $15 per workspace | ## All commands from your terminal. Source: [Knotbind CLI](https://docs.knotbind.com/docs/cli) The Knotbind CLI is a single executable with no extra dependencies. It covers everything from local OpenAPI-to-MCP generation to scheduled Checks, fix proposals and Owner approvals. Install it once and use it in scripts, CI, or locally. ## Install The CLI ships in this repository. Install it globally: ```sh npm install -g knotbind ``` Or run it directly without installing: ```sh npx knotbind --help ``` Or from a local checkout: ```sh node bin/knotbind.mjs --help ``` ## Configuration All commands read two environment variables: Variable | Default | Required for | KNOTBIND_URL | https://www.knotbind.com | All commands (points the CLI at your region) | KNOTBIND_API_KEY | — | Everything except readiness, signup, openapi-to-mcp, modules list | Get your API key from the Dashboard (https://www.knotbind.com/dashboard) or by running{" "} `knotbind signup`. ## Public commands These run without an API key. They do not authenticate to your workspace. ### readiness Runs a read-only Agent Readiness Check against any website or MCP server. Outputs a score out of 100 with a fix list. ```sh knotbind readiness https://api.your-business.example.com ``` Options Flag | Description | --depth | Maximum number of OpenAPI operations to inspect (default 20). | --format | Output format: json or text (default text). | ### signup Creates a new workspace and prints the first API key. The email and company name must not already exist. ```sh knotbind signup --company Acme --name "Jane Doe" --email jane@acme.example ``` ### openapi-to-mcp Generates an MCP server from an OpenAPI description. Reads a local JSON file or fetches from a URL. ```sh knotbind openapi-to-mcp ./openapi.json --ops list_users,get_user --max 100 ``` Options Flag | Description | --max <n> | Limit to the first n operations (default 50, max 100). | --ops op1,op2,... | Select specific operations by their operationId. | --format package | Output a distributable server package. | --out <file> | Write the package to this path (default: stdout for JSON, ./server.tar.gz for package). | --allow-write | Generate mutating tools. Requires Owner approval before Checks can run. | --auth bearer|apiKey|basic | Auth scheme to declare on the generated MCP server. | --auth-header X-My-Header | Custom header name for API key auth. | Package format With `--format package`, the CLI produces a `server.tar.gz` containing an executable MCP server. Run it directly or deploy a private endpoint. ```sh knotbind openapi-to-mcp ./openapi.json --format package --out server.tar.gz --allow-write node server.tar.gz --mcp ``` ## Connected commands These commands require `KNOTBIND_API_KEY`. They act on your workspace. ### connect Registers an MCP server for monitoring. The URL must be public HTTPS. ```sh knotbind connect https://mcp.your-business.example/mcp ``` ### status Prints health, open Findings, scheduled Checks and the last Run result. ```sh knotbind status ``` ### run Runs all scheduled Checks now. Use this for an on-demand verification. ```sh knotbind run ``` ### tools Lists live tools from the MCP server you registered. ```sh knotbind tools ``` ### tool-call Calls one MCP tool once. Not scheduled. Write tools require `--allow-write` and Owner approval. ```sh knotbind tool-call get_customer --args '{"id": "123"}' ``` ### finding Opens a Finding, its diagnosis, and the Repair Proposal. ```sh knotbind finding ``` ### runs Shows recent Check Runs. ```sh knotbind runs --limit 10 ``` ### add-check Adds a Check for a tool. Write-capable tools require `--allow-write`. ```sh knotbind add-check get_user --allow-write ``` ### remove-check Removes a previously added Check by ID. ```sh knotbind remove-check chk_123abc ``` ### assistants Shows which AI Assistants (ChatGPT, Claude, Grok, Meta Muse, and many more) are currently connected through your relay. ```sh knotbind assistants ``` ### relay Creates a relay URL that records the connecting assistant's identity. Shown only once, then expires. ```sh knotbind relay ``` ### mcp-config Prints a ready-to-paste MCP client configuration for connecting an AI Assistant to your Knotbind MCP server. ```sh knotbind mcp-config ``` ### request-plan Sends an Owner-approved plan change request (Pro or Business). ```sh knotbind request-plan business --reason "Need EU hosting" ``` ### keys Lists API keys, creates a new key, or revokes an existing one. ```sh knotbind keys knotbind keys create --scopes read,write knotbind keys revoke key_abc123 ``` ## Gateway modules Manage Gateway modules from the CLI. ```sh knotbind modules knotbind modules enable-all knotbind modules disable semantic_cache ``` ## Examples ### CI: fail the build on a breaking API change ```sh KNOTBIND_API_KEY=kb_live_... knotbind run # Exit non-zero if any Check failed ``` ### Local: generate and test an MCP server ```sh knotbind openapi-to-mcp ./api.json --ops list,get --format package --out server.tar.gz node server.tar.gz --mcp & knotbind readiness http://localhost:3000/mcp --depth 10 ``` ## Error handling The CLI prints JSON to stdout and human-readable text to stderr. On failure, the exit code is non-zero and the error message includes the HTTP status and a `knot_error` field: ```json {"error":"KNOTBIND_API_KEY is required for this command","knot_error":"unauthorized"} ``` ## Start free. Scale when the connection matters. Source: [Plans & billing](https://docs.knotbind.com/docs/billing) Free, Pro at $199 per month, and Business at $399 per month. Enterprise is agreed in writing and is not a checkout plan. Card data never touches Knotbind. See the full comparison on the pricing page. View plans and compare limits ## Plan behavior Plan | Checks | Frequency | Repair | Build / EU | Free | 3 | Daily | Detect and email | – | Pro · $199/month | 10 | Hourly | Diagnose and verify | Gateway | Business · $399/month | 25 | Every 5 minutes | Deploy webhook | Build + EU | ## Agent upgrade ```sh curl -X POST https://www.knotbind.com/api/v1/billing/checkout \ -H "authorization: Bearer $KNOTBIND_API_KEY" \ -H 'content-type: application/json' \ -d '{"plan":"pro"}' ``` What happens The response contains a Stripe Checkout URL. A person opens it and pays. Stripe's signed webhook updates the plan, schedule interval and entitlements. Payment failure starts a seven-day grace period. ## What Knotbind limits, and what it does not claim. Source: [Limits and non-claims](https://docs.knotbind.com/docs/limits) The numbers that apply to every plan, and the things a passing Check or a successful call does not prove. Feature pages stay short because this is collected here. ## Plan limits | Free | Pro | Business | Price | $0 | $199 per month | $399 per month | Active Checks, across all servers | 3 | 10 | 25 | Checks run | Daily | Hourly | Every 5 minutes | History | 7 days | 90 days | 365 days | Members | 1 | 5 | 20 | Mend: GitHub repos, your own APIs | 1, 1 | 5, 3 | 20, 10 | Knotbind suggests one contract Check for each tool, but only approved Checks count against the limit. See MCP servers (https://docs.knotbind.com/docs/mcp-servers). ## API limits Request rates, body size and retry rules are on the Agent API (https://docs.knotbind.com/docs/agent-api#errors) page. Credential vault limits are on Credential vault (https://docs.knotbind.com/docs/credential-vault). ## What Knotbind does not claim When you see | It does not prove | A passing contract Check | That Claude, ChatGPT or Cursor has connected. Real client proof is recorded separately or detected through the relay. | An approved repair | That your API or repository changed. Approval changes Knotbind's Check. See Reliability. | A successful tool call | That an order was placed or a payment was made. Read the run's evidence. | A Mend pull request | That the fix is right. Mend states a confidence and your tests' result; you review and merge. | An Apify run that succeeded | That an MCP tool, schema or agent workflow still works. | A demo run | Anything about your production system. | ## What is not built yet - A single assistant-facing tool set that searches, describes and calls businesses through Knotbind. Today an agent reads the directory (https://www.knotbind.com/directory.json), connects to a server, and uses its tools. - A status page for Knotbind itself, and a deprecation period for the API. See Changes and versioning (https://docs.knotbind.com/docs/changelog). - A standard data processing agreement and a subprocessor list. If you need one, ask; terms are agreed in writing before your data is stored. See Security (https://www.knotbind.com/security) for what is documented today. - Agent payments on Stripe's Machine Payments Protocol and on x402. Today an agent can only buy a Knotbind plan by card, inside an Owner-created payment mandate. ## What changed, and what is promised. Source: [Changes and versioning](https://docs.knotbind.com/docs/changelog) The version of the API, what Knotbind does and does not commit to when it changes, and a dated list of changes you can see. ## Versions The REST API lives under `/api/v1` and its contract is at /openapi.json (https://www.knotbind.com/openapi.json). The Knotbind MCP server at `/mcp` exposes the same operations. There is no `v2`. ## What is not promised yet No notice period Knotbind has not published a deprecation period or a compatibility guarantee for /api/v1. Do not build on an assumption that a field or error code will stay. Changes are listed below after they ship. If you need a written commitment, ask: it can be agreed with you in a contract. Knotbind also has no status page yet. A server that Knotbind cannot reach is reported to you as a Finding and an alert, but an outage of Knotbind itself is not announced anywhere. ## Changes Date | Change | 2026-11-03 | Agents can keep memory between sessions, post to shared threads and find notes by meaning (Pro and Business, switched on by the Owner). A server that fails three times in a row is no longer called until its next probe. | 2026-11-03 | A relay accepts its token in the X-Knotbind-Relay-Token header as well as in the URL. Public docs rewritten around safe agent actions, with an Agent API page that lists errors, limits and retry rules. | 2026-11-03 | Approval alerts, reversal of a finished agent run, Approve all read-only, and the last 20 Check results on each server card. | 2026-11-02 | Mend can repair a customer MCP server's source and supports Python repositories. Payment mandates: an agent cannot pay without one an Owner created. | 2026-10-30 | Mend finds affected lines with the TypeScript compiler, scores severity by rule, and explains each change. Two-factor sign-in. | 2026-10-28 | Sign in with Google or Apple. Deeper MCP readiness checks. | 2026-10-27 | Documentation moved to docs.knotbind.com, with MCP discovery files. | 2026-10-16 | The native Knotbind Gateway: an OpenAI-compatible endpoint with an access key, a budget and a rate limit per app. | 2026-10-15 | Free, Pro and Business plans with Stripe billing. OAuth 2.1 sign-in for the API and MCP server. The relay that records which assistant connects. | ## The words Knotbind uses. Source: [Glossary](https://docs.knotbind.com/docs/glossary) One list of the capitalized terms across the docs. Two words, Provider and Workflow, mean different things in different parts of Knotbind, and both meanings are given. ## People and workspace Term | Means | Account | A workspace: the company, its members, servers, Checks, keys and records. | Owner | The person who approves changes and releases agent actions. An agent, an API key or an MCP tool cannot. | Audit Record | The append-only history of Runs, Findings, repairs, approvals and agent actions, with who did each. | ## Monitoring Term | Means | Check | A repeatable test of one tool or endpoint. Suggested by Knotbind, approved by the Owner, then run on a schedule. | Run | One execution of Checks, with status, latency and a response preview. | Baseline | The shape of an answer the last time it passed. A different shape fails the Check, so a change nobody announced is still caught. | Drift | A difference between the current API or tool schema and its Baseline. | Finding | A reported problem: opens after two consecutive failures or on Breaking Drift, with a diagnosis. | Repair Proposal | A reviewable change drafted for a Finding and verified in the Sandbox before the Owner sees it. | Sandbox | A non-production target Checks run against: Knotbind's demo server or your staging API. | Reliability Loop | Check, detect, diagnose, propose, approve, resolve. | ## Agent actions Term | Means | Provider (actions) | A business's MCP server an agent can act on, such as a restaurant's booking server. | Workflow (actions) | An ordered list of tool calls on one provider, each with a risk class. | Risk class | read, quote, reserve, create, pay or cancel. It decides whether a step waits for the Owner. | Policy | The Owner's standing permission for one agent and one workflow, with a cap and an expiry. | Payment mandate | The Owner's written limit on what one agent may spend. Without one an agent cannot pay. | Credential vault | Encrypted upstream credentials. An agent gets the right to run one operation, never the secret. | Relay URL | A URL that lets an assistant reach your MCP server through Knotbind, so the connecting assistant can be recorded. | ## Other products Term | Means | Workflow Check (monitoring) | A multi-step Check that calls several tools in order and asserts on the results. Not a write workflow. | Provider (Mend) | A third-party API that your code calls, such as Stripe or OpenAI, tracked from its published description. | Mend | Opens a draft pull request when a third-party API changes in a way that breaks your code. | Gateway | A managed OpenAI-compatible AI gateway with an access key, a monthly budget and a request rate per app. | Gateway module | A paid add-on to the Gateway: Semantic Cache, Content Guardrails, Model Failover, Advanced Rate Limits or Request Analytics. |