Overview

bknd includes a fully featured MCP server that can be used to interact with the bknd instance. It uses a lightweight MCP implementation that works in any environment bknd works in. Unlike other MCP servers, the exposed tools and resources are mainly dynamically generated from the schema, extracted from defined hono routes, and manually defined ones. This means exposed tools and resources are always up to date, and requires little overhead to maintain.

• Fully featured, always up to date MCP server natively integrated with bknd
• Integrated MCP UI accessible from the Admin UI
• Built-in MCP client directly usable from your app instance
• CLI command to run an MCP server on stdio transport

Integrated MCP UI

Once enabled, you can access the MCP UI at /mcp, or choose "MCP" from the top right user menu.

Enable MCP

If you're using initialConfig, you can enable the MCP server by setting the server.mcp.enabled property to true.

import type { BkndConfig } from "bknd";

export default {
   initialConfig: {
      server: {
         mcp: {
            enabled: true,
         }
      }
   }   
} satisfies BkndConfig;

Using the Admin UI, you can either navigate to /settings/server or click top right on the user menu, select "Settings", then "Server". Enable the MCP server by checking the "Enabled" checkbox under "Mcp".

Using the MCP Client

The implementation is closely following the MCP spec 2025-06-18 powered by jsonv-ts, therefore any spec compliant client will work. However, there is a built-in MCP client:

import { McpClient } from "bknd/utils";

const client = new McpClient({
   url: "http://localhost:1337/api/system/mcp",
});

Alternatively, similar to the getApi function, you can use the getMcpClient function to get the client from your app instance that doesn't travel through the network.

import { createApp } from "bknd";

const app = createApp();
const client = app.getMcpClient();

Unlike the official spec requires, there is no initialization required, but supported. Without connecting, initialization or fetching the list of tools, you can directly call them. For example, you could fetch a list of posts:

const result = await client.callTool({
   name: "data_entity_read_many",
   arguments: {
      entity: "posts",
      limit: 3,
      select: ["id", "title"],
   },
});
// {
//    data: [
//       { id: 1, title: "Post 1" },
//       { id: 2, title: "Post 2" },
//       { id: 3, title: "Post 3" }
//    ],
// }

Refer to the jsonv-ts docs for more information.

STDIO Transport

To start an MCP server on stdio transport, you can use the mcp CLI command. This is useful when you want to use it with IDEs or other tools that support stdio transport.

npx bknd mcp

If you want have the Streamable HTTP endpoint disabled, you can still use the STDIO transport by passing the --force option.

npx bknd mcp --force

Usage in external tools

You can also use the MCP server in external tools, such as VS Code, Cursor, or other IDEs that support MCP. This list is not exhaustive, and will be updated.

If a tool you're using is not listed here, please let us know by opening an issue or contacting us on Discord.

Authentication

Both the Streamable HTTP and STDIO transport support authentication. The same authentication mechanism as the API is used, so permissions work the exact same way.

When using the Streamable HTTP transport, you can pass the Authorization header to the client.

const client = new McpClient({
   url: "http://localhost:1337/api/system/mcp",
   headers: {
      Authorization: `Bearer ${token}`,
   },
});

When using the STDIO transport, you can pass an --token option to the CLI command.

npx bknd mcp --token <token>

Alternatively, you can also use the BEARER_TOKEN environment variable.

BEARER_TOKEN=<token> npx bknd mcp