> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to the Knock MCP server

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.

**Authentication:** OAuth 2.1/DCR
**Categories:** Communication, Developer Tools
**Tools:** 25: 17 read, 0 write, 8 destructive
**Users sign in with:** OAuth
**OAuth app:** Your own Knock MCP server app
**Built by:** Vendor MCP
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=KNOCKMCP)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".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](/agentkit/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

   **Node.js** (`quickstart.mts`)

   ```typescript
   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)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "knockmcp"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Knock MCP:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={"context":"YOUR_CONTEXT","llm_model":"claude-opus-4-8"},
       tool_name="knockmcp_get_more_tools",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'knockmcp_execute_mapi_read',
  toolInput: {
    code: '<code>',
    context: '<context>',
    llm_model: 'claude-opus-4-8',
  },
  connector: 'knockmcp',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="knockmcp_execute_mapi_read",
    tool_input={
        "code": "<code>",
        "context": "<context>",
        "llm_model": "claude-opus-4-8",
    },
    connection_name="knockmcp",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `knockmcp_execute_mapi_read`

Execute MAPI (read) · Read-only

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 };

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 };
}

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `code` (`string`, required): JavaScript async arrow function to execute
- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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_id` (`string`, optional): 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.

Example input: `{"code":"<code>","context":"<context>","llm_model":"claude-opus-4-8"}`

### `knockmcp_get_knock_agent`

Get Knock agent status · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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_id` (`string`, required): Agent session ID from start_knock_agent
- `conversation_id` (`string`, optional): 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.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8","session_id":"<session_id>"}`

### `knockmcp_get_message`

Get message · Read-only

  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.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `messageId` (`string`, required): (string): The ID of the message to retrieve.
- `conversation_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to retrieve the message from. Defaults to `development`.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8","messageId":"<messageId>"}`

### `knockmcp_get_message_content`

Get message content · Read-only

  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.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `messageId` (`string`, required): (string): The messageId of the message to retrieve.
- `conversation_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to retrieve the message from. Defaults to `development`.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8","messageId":"<messageId>"}`

### `knockmcp_get_message_delivery_logs`

Get message delivery logs · Read-only

  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.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `messageId` (`string`, required): (string): The ID of the message to retrieve delivery logs for.
- `conversation_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to retrieve the delivery logs from. Defaults to `development`.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8","messageId":"<messageId>"}`

### `knockmcp_get_message_events`

Get message events · Read-only

  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.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `messageId` (`string`, required): (string): The ID of the message to retrieve events for.
- `conversation_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to retrieve the message events from. Defaults to `development`.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8","messageId":"<messageId>"}`

### `knockmcp_get_more_tools`

Get More Tools · Read-only

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

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `context` (`string`, required): A description of your goal and what kind of tool would help accomplish it.
- `llm_model` (`string`, required): 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_id` (`string`, optional): 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.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8"}`

### `knockmcp_get_object`

Get object · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `collection` (`string`, required): (string): The collection to get the object from.
- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `objectId` (`string`, required): (string): The ID of the object to get.
- `conversation_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to get the object from. Defaults to `development`.

Example input: `{"collection":"<collection>","context":"<context>","llm_model":"claude-opus-4-8","objectId":"<objectId>"}`

### `knockmcp_get_tenant`

Get tenant · Read-only

  Retrieves a tenant by their ID. Tenants in Knock are used to model organizations, teams, and other groups of users. They are a special type of object.

  Use this tool when you need to lookup the information about a tenant, including name, and if there are any custom properties set.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `tenantId` (`string`, required): (string): The ID of the tenant to retrieve.
- `conversation_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to retrieve the tenant from. Defaults to `development`.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8","tenantId":"<tenantId>"}`

### `knockmcp_get_user`

Get user · Read-only

   Retrieves the complete user object for the given userId, including email, name, phone number, and any custom properties. Use this tool when you need to retrieve a user's complete profile.

   If the userId is not provided, it will use the userId from the config.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to retrieve the user from. Defaults to `development`.
- `userId` (`string`, optional): (string): The userId of the User to retrieve.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8"}`

### `knockmcp_get_user_messages`

Get user messages · Read-only

  Retrieves the messages that this user has received from the service. Use this tool when you need information about the notifications that the user has received, including if the message has been read, seen, or interacted with. This will return a list of messages across all of the channels.

  If the userId is not provided, it will use the userId from the config.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to retrieve the user messages from. Defaults to `development`.
- `userId` (`string`, optional): (string): The userId of the User to retrieve messages for.
- `workflowRunId` (`string`, optional): (string): The workflowRunId of the User to retrieve. Use this when you want to retrieve messages sent from a workflow trigger.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8"}`

### `knockmcp_get_user_preferences`

Get user preferences · Read-only

  Retrieves the user's notification preferences for the given userId.

  If the userId is not provided, it will use the userId from the config. 

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to retrieve the user preferences from. Defaults to `development`.
- `preferenceSetId` (`string`, optional): (string): The preferenceSetId of the User to retrieve preferences for. Defaults to `default`.
- `userId` (`string`, optional): (string): The userId of the User to retrieve Preferences for.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8"}`

### `knockmcp_list_environments`

List environments · Read-only

  Lists all environments available, returning the slug and name of each environment. Use this tool when you need to see what environments are available.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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_id` (`string`, optional): 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.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8"}`

### `knockmcp_list_objects`

List objects · Read-only

List all objects in a single collection. Objects are used to model custom collections in Knock that are NOT users or tenants. Use this tool when you need to return a paginated list of objects in a single collection.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `collection` (`string`, required): (string): The collection to list objects from.
- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to list objects from. Defaults to `development`.

Example input: `{"collection":"<collection>","context":"<context>","llm_model":"claude-opus-4-8"}`

### `knockmcp_list_tenants`

List tenants · Read-only

  Retrieves a list of tenants. Tenants in Knock are used to model organizations, teams, and other groups of users. They are a special type of object. 

  Use this tool when you need to list all tenants in an environment.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to retrieve the tenants from. Defaults to `development`.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8"}`

### `knockmcp_search_documentation`

Search documentation · Read-only

Search the Knock documentation for a given query

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `query` (`string`, required): The query to search the documentation for
- `conversation_id` (`string`, optional): 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.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8","query":"<query>"}`

### `knockmcp_search_mapi`

Search MAPI OpenAPI · Read-only

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 `search_mapi` to explore or filter the OpenAPI spec for the **mapi** API before calling `execute_mapi_read` or `execute_mapi_write`. All $ref pointers are pre-resolved inline.

Types:
// OpenAPI 3.x spec with $refs resolved inline.
interface OperationObject {
  summary?: string;
  description?: string;
  operationId?: string;
  tags?: string[];
  parameters?: Array<{
    name: string;
    in: "query" | "header" | "path" | "cookie";
    required?: boolean;
    schema?: unknown;
    description?: string;
  }>;
  requestBody?: { required?: boolean; content?: Record<string, { schema?: unknown }> };
  responses?: Record<string, { content?: Record<string, { schema?: unknown }> }>;
}
interface PathItem {
  get?: OperationObject; post?: OperationObject; put?: OperationObject;
  patch?: OperationObject; delete?: OperationObject;
}
interface OpenApiSpec {
  openapi: string;
  info: { title: string; version: string; description?: string };
  paths: Record<string, PathItem>;
  servers?: Array<{ url: string }>;
  components?: Record<string, unknown>;
  tags?: Array<{ name: string; description?: string }>;
}
declare const mapi: { spec(): Promise };

Your code must be a single JavaScript async arrow function (no TypeScript) that returns a small, filtered result.
Example:
async () => {
  const spec = await mapi.spec();
  return Object.keys(spec.paths).slice(0, 20);
}

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `code` (`string`, required): JavaScript async arrow function to search the spec
- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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_id` (`string`, optional): 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.

Example input: `{"code":"<code>","context":"<context>","llm_model":"claude-opus-4-8"}`

### `knockmcp_execute_mapi_write`

Execute MAPI (write) · Destructive

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_write`) for **write** `MAPI` calls at https://control.knock.app via `mapi.request({ method: "POST"|"PUT"|"PATCH"|"DELETE", ... })`. 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 `GET`, use `execute_mapi_read` 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: "POST" | "PUT" | "PATCH" | "DELETE";
  path: string;
  query?: Record<string, string | number | boolean | undefined>;
  body?: unknown;
  contentType?: string;
  rawBody?: boolean;
  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 };

Your code must be a single JavaScript async arrow function (no TypeScript).
Example:
async () => {
  const res = await mapi.request({
    method: "PUT",
    path: "/v1/workflows/welcome",
    body: { name: "Welcome", steps: [] },
  });
  return { status: res.status, result: res.result };
}

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `code` (`string`, required): JavaScript async arrow function to execute
- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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_id` (`string`, optional): 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.

Example input: `{"code":"<code>","context":"<context>","llm_model":"claude-opus-4-8"}`

### `knockmcp_set_user_preferences`

Set user preferences · Destructive

  Overwrites the user's notification preferences for the given userId. Allows setting per-workflow, per-category, or per-channel notification preferences. Use this tool when you are asked to update a user's notification preferences.

  If the userId is not provided, it will use the userId from the config.

  Instructions:

  - You must ALWAYS provide a full preference set to this tool.
  - When setting per-workflow preferences, the key in the object should be the workflow key.
  - Workflow and category preferences should always have channel types underneath.
  - The channel types available to you are: email, sms, push, chat, and in_app_feed.
  - To turn OFF a preference, you must set it to false.
  - To turn ON a preference, you must set it to true.

  <examples>
    <example>
      <description>
        Update the user's preferences to turn off email notifications for the "welcome" workflow.
      </description>
      <input>
        {
          "workflows": {
            "welcome": {
              "channel_types": {
                "email": false
              }
            }
          }
        }
    </example>
  </examples>

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `categories` (`object`, optional): (object): The categories to update where the key is the category key, and the value of the object is an object that contains a `channel_types` key with a boolean value for each channel type.
- `channel_types` (`object`, optional): (object): The channel types to update where the key is the channel type, and the value of the object is a boolean value.
- `conversation_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to set the user preferences in. Defaults to `development`.
- `userId` (`string`, optional): (string): The userId of the User to update preferences for.
- `workflows` (`object`, optional): (object): The workflows to update where the key is the workflow key, and the value of the object is an object that contains a `channel_types` key with a boolean value for each channel type.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8"}`

### `knockmcp_start_knock_agent`

Start Knock agent · Destructive

Use Knock's hosted agent to create and update workflows, broadcasts, guides, email layouts, partials, and translations.

Prefer this tool when creating or updating those resources in a Knock account — the hosted agent has full account context and usually needs fewer tokens than calling the Management API directly. Use Management API code mode (`search_mapi` / `execute_mapi_read` / `execute_mapi_write`) when you need a specific API call, or when the user asks to use the API.

For analytics questions, the Knock agent can return high-level message and engagement data. Those queries are not available through the Management API.

Pass the user's request verbatim in prompt. Do not reinterpret or shorten it.

This tool waits up to ~45 seconds, then returns a consolidated result. Read the Status line in the response:
- Status: complete — the run finished; use the agent response and modified resources.
- Status: error — the run failed; read the Error line.
- Status: running — the run is still going; save the Session ID and poll with get_knock_agent until Status is complete or error.

Agents can support follow-up runs by passing in the returned session_id. Use a follow-up run only for related edits or questions about a resource you just modified. Otherwise, use the Management API or start a new agent session.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `prompt` (`string`, required): The user's full request, passed verbatim to the Knock agent
- `conversation_id` (`string`, optional): 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.
- `session_id` (`string`, optional): Existing agent session ID for follow-up runs

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8","prompt":"<prompt>"}`

### `knockmcp_subscribe_users_to_object`

Subscribe users to object · Destructive

  Subscribe a list of users to an object in a specific collection. We use this to model lists of users, for pub-sub use cases.

  Use this tool when you need to subscribe one or more users to an object where you will then trigger workflows for those lists of users to send notifications to.

  Before using this tool, you should create the object in the collection using the createOrUpdateObject tool.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `collection` (`string`, required): (string): The collection to subscribe the user to.
- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `objectId` (`string`, required): (string): The ID of the object to subscribe the user to.
- `userIds` (`array`, required): (array): The IDs of the users to subscribe to the object. If not provided, the current user will be subscribed.
- `conversation_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to subscribe the user to. Defaults to `development`.

Example input: `{"collection":"<collection>","context":"<context>","llm_model":"claude-opus-4-8","objectId":"<objectId>","userIds":[]}`

### `knockmcp_unsubscribe_users_from_object`

Unsubscribe users from object · Destructive

Unsubscribe a list of users from an object in a specific collection. We use this to model lists of users, for pub-sub use cases.

  Use this tool when you need to unsubscribe one or more users from an object where you will then trigger workflows for those lists of users to send notifications to.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `collection` (`string`, required): (string): The collection to unsubscribe the user from.
- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `objectId` (`string`, required): (string): The ID of the object to unsubscribe the user from.
- `userIds` (`array`, required): (array): The IDs of the users to unsubscribe from the object.
- `conversation_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to unsubscribe the user from. Defaults to `development`.

Example input: `{"collection":"<collection>","context":"<context>","llm_model":"claude-opus-4-8","objectId":"<objectId>","userIds":[]}`

### `knockmcp_upsert_object`

Create or update object · Destructive

Create or update an object in a specific collection. Objects are used to model custom collections in Knock that are NOT users or tenants. If the object does not exist, it will be created. If the object exists, it will be updated with the provided properties. The update will always perform an upsert operation, so you do not need to provide the full properties each time.

  Use this tool when you need to create a new object, or update an existing custom-object. Custom objects can be used to subscribe users' to as lists, and also send non-user facing notifications to.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `collection` (`string`, required): (string): The collection to create or update the object in.
- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `objectId` (`string`, required): (string): The ID of the object to create or update.
- `conversation_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to create or update the object in. Defaults to `development`.
- `properties` (`object`, optional): (object): The properties to set on the object.

Example input: `{"collection":"<collection>","context":"<context>","llm_model":"claude-opus-4-8","objectId":"<objectId>"}`

### `knockmcp_upsert_tenant`

Create or update tenant · Destructive

  Creates or updates a tenant using the properties provided. Tenants in Knock are used to model organizations, teams, and other groups of users. They are a special type of object.

  Use this tool when you need to create a new tenant, or update an existing tenant's properties.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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.
- `tenantId` (`string`, required): (string): The ID of the tenant to update.
- `conversation_id` (`string`, optional): 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.
- `environment` (`string`, optional): (string): The environment to set the tenant in. Defaults to `development`.
- `name` (`string`, optional): (string): The name of the tenant.
- `properties` (`object`, optional): (object): The properties to set on the tenant.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8","tenantId":"<tenantId>"}`

### `knockmcp_upsert_user`

Create or update user · Destructive

  Creates a new user if they don't exist, or updates the user object for the given userId, including email, name, phone number, and any custom properties.

  Use this tool when you need to update a user's profile.

  If the userId is not provided, it will use the userId from the config.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `context` (`string`, required): Describe the user's underlying goal in one sentence, rather than the tool being called.
- `llm_model` (`string`, required): 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_id` (`string`, optional): 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.
- `customProperties` (`object`, optional): (object): A dictionary of custom properties to update for the User.
- `email` (`string`, optional): (string): The email of the User to update.
- `environment` (`string`, optional): (string): The environment to create or update the user in. Defaults to `development`.
- `name` (`string`, optional): (string): The name of the User to update.
- `phoneNumber` (`string`, optional): (string): The phone number of the User to update.
- `userId` (`string`, optional): (string): The userId of the User to update.

Example input: `{"context":"<context>","llm_model":"claude-opus-4-8"}`

## Related

Other Communication connectors ([all 132](/agentkit/connectors/?category=communication)):

- [Gmail](/agentkit/connectors/gmail/): Scalekit connector, OAuth, 48 tools
- [Slack](/agentkit/connectors/slack/): Scalekit connector, OAuth, 96 tools
- [Google Calendar](/agentkit/connectors/googlecalendar/): Scalekit connector, OAuth, 30 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
