Knotbind documentationOpen dashboard
Guide: Connect an MCP server

Register and authenticate your 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.

  1. Name

    A label for the server (for example Production API or Staging MCP). Each name can be used once in your workspace.

  2. 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.

  3. Authentication

    How Knotbind signs in: None, Bearer token or API key header. OAuth is set up afterwards, see below.

  4. 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.

$ 
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Choose Bearer token and paste the token as the credential. Knotbind sends it with each request to that server.

API key header

Use this when your server expects a key in a header of its own, such as X-API-Key.

$ 
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

  1. 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."

  2. 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.

  3. 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.

  • 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