Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the Knock MCP server

Vendor MCP
Open markdown

The Knock MCP connector routes your AI agent's tool calls to Knock's own MCP server through Scalekit. Each user signs in to Knock once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 25 tools.

Tools
25
What they doRead · write · destructive
17 · 0 · 817 read0 write8 destructive
Users sign in with
OAuth app
Your own Knock MCP server app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the Knock MCP connection

    In AgentKit > Connections, create a Knock MCP connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    Knock MCP server connections use your own OAuth app. Register one with Knock MCP server and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Knock MCP connection.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'knockmcp'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Knock MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'knockmcp_get_more_tools',
    toolInput: { context: 'YOUR_CONTEXT', llm_model: 'claude-opus-4-8' },
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • knockmcp_execute_mapi_readThis is the Management API: workflows, channels, templates, commits, and configuration.Read-only

    Execute MAPI (read)

    This is the Management API: workflows, channels, templates, commits, and configuration. This session allows **read and write**. Use `execute_mapi_read` for `GET` and `execute_mapi_write` for `POST`/`PUT`/`PATCH`/`DELETE`. Use this tool (Code Mode: `execute_mapi_read`) for **read-only** `MAPI` calls at https://control.knock.app via `mapi.request({ method: "GET", ... })`. Use `search_mapi` first to find paths and request shapes. Auth headers are added on the host. Omit `environment` to use the account's default environment; callers can explicitly target another environment by adding it to `query`. For create/update/delete, use `execute_mapi_write` instead. **mapi.request() response shape:** does NOT return the API JSON body directly. It wraps it: ```json { "status": 200, "ok": true, "result": { /* actual API response body */ } } ``` Always read API fields from `res.result`, not from `res` (e.g. `res.result.entries`, not `res.entries`). When the user asks for the "exact result," return the full `mapi.request(...)` value unless they ask for a projection. Types: interface RequestOptions { method: "GET"; path: string; query?: Record<string, string | number | boolean | undefined>; headers?: Record<string, string>; } /** Wrapper returned by mapi.request() — the API body is in `result`, not at the top level. */ interface RequestResponse { status: number; ok: boolean; result: unknown; } declare const mapi: { request(options: RequestOptions): Promise<RequestResponse> }; Your code must be a single JavaScript async arrow function (no TypeScript). Example: async () => { const res = await mapi.request({ method: "GET", path: "/v1/workflows", }); return { status: res.status, entries: res.result.entries, page_info: res.result.page_info }; }

    Inputs

    codestringrequired
    JavaScript async arrow function to execute
    contextstringrequired
    Describe the user's underlying goal in one sentence, rather than the tool being called.
    llm_modelstringrequired
    The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess.
    conversation_idstring
    Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
  • knockmcp_get_knock_agentPoll an in-progress Knock agent session and return a consolidated result (agent text, tool calls, modified resources, and a Status line).Read-only

    Get Knock agent status

    Poll an in-progress Knock agent session and return a consolidated result (agent text, tool calls, modified resources, and a Status line). When to use: - After start_knock_agent returns Status: running. - When resuming after an MCP disconnect (you still have the session_id). How to use: 1. Call with the session_id from start_knock_agent (or a prior get_knock_agent). 2. Read the Status line in the tool result — you do not parse raw events; the server consolidates them for you. 3. If Status is running, wait a few seconds and call get_knock_agent again with the same session_id. 4. If Status is complete, the run succeeded — use the agent response. 5. If Status is error, the run failed — read the Error line. The Knock agent keeps running on the backend between your polls; each call is short-lived.

    Inputs

    contextstringrequired
    Describe the user's underlying goal in one sentence, rather than the tool being called.
    llm_modelstringrequired
    The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess.
    session_idstringrequired
    Agent session ID from start_knock_agent
    conversation_idstring
    Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
  • knockmcp_get_messageRetrieves a single message by its ID, including its current status and engagement statuses (e.g.Read-only

    Get message

    Retrieves a single message by its ID, including its current status and engagement statuses (e.g. seen, read, interacted, link_clicked). Use this tool when you need to check the delivery status or engagement state of a specific message.

    Inputs

    contextstringrequired
    Describe the user's underlying goal in one sentence, rather than the tool being called.
    llm_modelstringrequired
    The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess.
    messageIdstringrequired
    (string): The ID of the message to retrieve.
    conversation_idstring
    Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
    environmentstring
    (string): The environment to retrieve the message from. Defaults to `development`.
  • knockmcp_get_message_contentRetrieves the complete contents of a single message, specified by the messageId.Read-only

    Get message content

    Retrieves the complete contents of a single message, specified by the messageId. The message contents includes the rendered template that was sent to the recipient. Use this tool when you want to surface information about the emails, SMS, and push notifications that were sent to a user.

    Inputs

    contextstringrequired
    Describe the user's underlying goal in one sentence, rather than the tool being called.
    llm_modelstringrequired
    The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess.
    messageIdstringrequired
    (string): The messageId of the message to retrieve.
    conversation_idstring
    Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
    environmentstring
    (string): The environment to retrieve the message from. Defaults to `development`.
  • knockmcp_get_message_delivery_logsRetrieves the delivery logs for a specific message.Read-only

    Get message delivery logs

    Retrieves the delivery logs for a specific message. Delivery logs contain details about each delivery attempt, including any errors that occurred. Use this tool when you need to debug why a message was not delivered or to inspect delivery attempt details.

    Inputs

    contextstringrequired
    Describe the user's underlying goal in one sentence, rather than the tool being called.
    llm_modelstringrequired
    The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess.
    messageIdstringrequired
    (string): The ID of the message to retrieve delivery logs for.
    conversation_idstring
    Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
    environmentstring
    (string): The environment to retrieve the delivery logs from. Defaults to `development`.
  • knockmcp_get_message_eventsRetrieves the event timeline for a specific message.Read-only

    Get message events

    Retrieves the event timeline for a specific message. Events include delivery, bounce, open, click, and other engagement events. Use this tool when you need to see the full lifecycle of a message.

    Inputs

    contextstringrequired
    Describe the user's underlying goal in one sentence, rather than the tool being called.
    llm_modelstringrequired
    The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess.
    messageIdstringrequired
    (string): The ID of the message to retrieve events for.
    conversation_idstring
    Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
    environmentstring
    (string): The environment to retrieve the message events from. Defaults to `development`.
  • knockmcp_get_more_toolsCheck for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.Read-only

    Get More Tools

    Check for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.

    Inputs

    contextstringrequired
    A description of your goal and what kind of tool would help accomplish it.
    llm_modelstringrequired
    The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess.
    conversation_idstring
    Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
  • knockmcp_get_objectGet an object wihin a collection.Read-only

    Get object

    Get an object wihin a collection. Returns information about the object including any custom properties. Use this tool when you need to retrieve an object to understand it's properties.

    Inputs

    collectionstringrequired
    (string): The collection to get the object from.
    contextstringrequired
    Describe the user's underlying goal in one sentence, rather than the tool being called.
    llm_modelstringrequired
    The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess.
    objectIdstringrequired
    (string): The ID of the object to get.
    conversation_idstring
    Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
    environmentstring
    (string): The environment to get the object from. Defaults to `development`.