MCP integration

Your knowledge base answers questions about things you have written down. An MCP server lets Minaya answer questions about things that change — order status, stock levels, booking availability — by calling your own systems during a conversation.

What MCP is

The Model Context Protocol is an open standard for exposing tools to AI systems. You run a server that advertises a set of tools; Minaya connects as a client, discovers what is available, and the model decides when to call one.

Minaya connects to remote MCP servers over Streamable HTTP. Local stdio servers are not supported — the server must be reachable from the internet.

How a call works

1. A visitor asks something.
2. Minaya retrieves relevant chunks as usual.
3. Tools from your enabled MCP servers are offered to the model alongside that context.
4. If the model calls a tool, Minaya connects to your server and executes it.
5. The result is fed back, and the model answers using it.

Tool calls resolve before the reply streams, so the visitor sees one clean answer rather than intermediate steps.

Connecting a server

Go to Integrations and add:

Minaya probes the server immediately and shows how many tools it found, or the error if it could not connect. Use Test to re-probe at any time.

Limits

If a server is unreachable, the conversation continues using your knowledge base alone — MCP failures never break the chat.

Building a server

Any MCP server implementation works. A minimal example using the TypeScript SDK:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "orders", version: "1.0.0" });

server.tool(
  "get_order_status",
  "Look up the delivery status of an order by its reference.",
  { orderId: z.string().describe("The customer's order reference") },
  async ({ orderId }) => {
    const order = await db.orders.findByReference(orderId);
    if (!order) {
      return { content: [{ type: "text", text: "No order with that reference." }] };
    }
    return {
      content: [{
        type: "text",
        text: `Order ${orderId}: ${order.status}, expected ${order.eta}.`,
      }],
    };
  },
);

Expose it over Streamable HTTP and give Minaya the URL.

Designing good tools

• Describe them plainly. The description is how the model decides whether to call a tool. “Look up the delivery status of an order by its reference” beats “order endpoint”.
• Keep parameters few and named clearly. The model fills them from conversation, so orderId works better than q.
• Return prose, not raw JSON. The result goes into the model's context; a readable sentence produces a better answer than a dumped object.
• Handle the empty case. Return “no order found” rather than an error, so the model can explain it.
• Keep them fast. A visitor is waiting; anything past 15 seconds is cut off.

Security

Because you supply a URL that Minaya's servers then call:

• Private addresses are blocked. Loopback, private ranges, link-local, CGNAT, and cloud metadata endpoints are rejected — validated both when you save and again before every connection, so DNS changes cannot bypass it.
• HTTPS is required in production.
• Tokens are encrypted at rest and never returned by the API.
• Tool metadata is treated as untrusted. A compromised server could hide instructions in a tool name or description, so metadata is sanitised and tools containing instruction-like text are dropped.
• Results are labelled as data. Tool output is wrapped so the model treats it as information, never as instructions.

See Security for the rest.

Managing servers

• Toggle — disable without deleting; disabled servers are not offered to the model.
• Test — re-probe and refresh the tool count.
• Delete — removes the server and its stored token.

Minaya as an MCP server

The sections above cover Minaya calling your systems. This is the other direction: your own AI tools querying the knowledge base you already built here.

Connect Claude, ChatGPT, or an agent you wrote, and it can search your content and ask grounded questions — the same retrieval and guardrails your website visitors get. Available on paid plans.

Connecting

1. Open Integrations in the dashboard and generate an access token under Minaya MCP server.
2. Copy it immediately — it is shown once. If you lose it, generate a new one; the old one stops working straight away.
3. Add the server to your MCP client:

{
  "mcpServers": {
    "minaya": {
      "type": "http",
      "url": "https://api.minaya.ai/public/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Tools

Security

• Read-only. No tool writes, updates, or deletes anything. A leaked token exposes only content your widget already serves publicly.
• Scoped to one widget. A token grants access to the knowledge base it was generated for, and nothing else on your account.
• Separate from your site key. The site key is public and sits in your page HTML. This token is secret — keep it out of client-side code and public repositories.
• Revoked on downgrade. Access is re-checked against your plan on every call.
• Rate limited to 60 calls a minute.