MCP — Internal Use

Miso runs a Model Context Protocol (MCP) server. It lets an AI assistant — Claude, an IDE agent, or your own tool-calling application — search your content and read the full text of what it finds.

This page covers the internal setup: one credential for your whole app, shared by your own team or one application you control.

To let each of your subscribers connect their own AI agent with their own login, see MCP Server for your Subscribers. The tools below are the same in both setups.

The assistant gets two tools:

A search tool, named for your brand. It returns short snippets from many articles at once.
A detail tool. It returns the full text of one snippet.

This two-step design keeps the assistant's context small. The assistant scans many short results first. Then it reads in full only what it needs.

Availability. Miso enables MCP per app and issues your token. To turn it on, contact your Miso representative.

Connect

Your MCP server URL looks like this:

https://api.askmiso.com/v1/ask/mcp?api_key=YOUR_KEY&token=YOUR_MCP_TOKEN

Miso gives you both values. Use your publishable API key. The MCP token is the access gate.

The transport is Streamable HTTP with JSON-RPC 2.0. Most clients call this "HTTP".

Claude Desktop

Open Settings ▸ Connectors ▸ Add custom connector. Paste the full server URL.

Claude Code

claude mcp add --transport http miso \
  "https://api.askmiso.com/v1/ask/mcp?api_key=YOUR_KEY&token=YOUR_MCP_TOKEN"

Add --scope project to write the server into a .mcp.json file that you can commit. Add --scope user to keep it private to your machine.

Cursor, VS Code, and Windsurf

Add this to your mcp.json:

{
  "mcpServers": {
    "miso": {
      "type": "http",
      "url": "https://api.askmiso.com/v1/ask/mcp?api_key=KEY&token=TOKEN"
    }
  }
}

Clients that support stdio only

Some clients cannot speak HTTP directly. Bridge them with mcp-remote:

npx mcp-remote https://api.askmiso.com/v1/ask/mcp \
  --header "Authorization: Bearer YOUR_MCP_TOKEN-YOUR_KEY"

Authentication formats

You can authenticate in either of two ways.

Method	How
Combined header	`Authorization: Bearer <MCP_TOKEN>-<API_KEY>`
Separate values	`X-API-Key` and `X-MCP-Token` headers, or the `api_key` and `token` query parameters

The combined header is the simplest form, and most MCP clients expect it. Use the query-parameter form for clients that cannot set headers.

Both values are always required. If the token does not match the one Miso issued for your app, the server returns 401.

%%{init: {'theme':'base','themeVariables':{
'fontFamily':'IBM Plex Sans, ui-sans-serif, system-ui','fontSize':'14px',
'actorBkg':'#3148be','actorBorder':'#3148be','actorTextColor':'#ffffff',
'actorLineColor':'#9aa3c0','signalColor':'#9aa3c0','signalTextColor':'#6b7392',
'labelBoxBkgColor':'#f4effc','labelBoxBorderColor':'#cdbcf0',
'labelTextColor':'#40277a','noteBkgColor':'#e8ecfb','noteBorderColor':'#b9c2ea',
'noteTextColor':'#22307a','sequenceNumberColor':'#ffffff'
}}}%%
sequenceDiagram
    autonumber
    participant U as A person
    participant AI as The AI assistant
    participant M as Miso MCP

    U->>AI: asks about your content
    AI->>M: search tool (question)
    M-->>AI: short snippets from many articles
    Note over AI: it scans the previews first

    AI->>M: detail tool (product_id, offset from that result)
    M-->>AI: the full passage
    Note over M: only ids a search returned are accepted, for one hour

    AI-->>U: an answer that cites your articles

The search tool

Miso names this tool for your brand, for example ask_yourbrand. Your Miso representative confirms the exact name.

Parameter	Type	Required	Notes
`question`	string	yes	The question to search for.
`context`	string	no	What the user is working on. Miso adds it to the question.
`skill_used`	string	no	The name of the skill or template that made the call. Used for analytics only.
`author`	string	no	Restrict results to one author. Available only if Miso enables it for your app.

The parameter is question, not query. A wrong name returns an error.

The author filter is fuzzy. Partial names, any casing, and small trailing typos all match. But the first letters must be correct. The response reports which author names matched.

There is no parameter for result count, paging, or filtering. Miso scopes the search to your catalog on the server side.

What search returns

{
  "query": "interest rate cuts",
  "results": [
    {
      "product_id": "art-20260612-rates",
      "product_title": "Central bank signals 2026 cuts",
      "authors": "A. Reporter",
      "offset": 1,
      "snippet_preview": "The central bank said it expects two cuts...",
      "published_date": "2026-06-12",
      "url": "https://example.com/markets/rates",
      "relevance_score": 0.87
    }
  ],
  "citation_format": "Use markdown links: [product_title](url) by authors"
}

Field	What it is
`product_id`	Pass this to the detail tool.
`offset`	Pass this to the detail tool. A negative value means a whole-work match.
`snippet_preview`	The first 300 characters, cut on a sentence boundary.
`relevance_score`	A score from 0 to 1.
`url`	The citation link.
`published_date`	Present when the article has a date.
`child_title`	The chapter or section, when there is one.
`matched_authors`	Present when you use the `author` filter.

If nothing matches, results is empty and the response carries a message.

The detail tool

The default name is get_snippet_detail. Miso can rename it for your brand.

Parameter	Type	Required	Notes
`product_id`	string	yes	From a search result.
`offset`	integer	yes	From the same search result.
`skill_used`	string	no	Analytics only.

Call the search tool first. The detail tool only accepts a product_id and offset that a search returned. Any other value is refused, and Miso records the attempt. A result stays readable for one hour after the search that found it. See Protecting your content.

What the detail tool returns

{
  "product_id": "art-20260612-rates",
  "product_title": "Central bank signals 2026 cuts",
  "authors": "A. Reporter",
  "offset": 1,
  "content": "The full text of the snippet...",
  "url": "https://example.com/rates",
  "citation_format": "[Central bank signals cuts](https://ex.com/r)",
  "citation_instruction": "ALWAYS cite using the markdown link."
}

The citation_format field holds a ready-made markdown link. The assistant is told to cite with it, so the reader can click straight through to your article.

Test the connection

Send three JSON-RPC calls: initialize, tools/list, then tools/call. Replace the tool name with your own.

BASE=https://api.askmiso.com/v1/ask/mcp
AUTH="Authorization: Bearer YOUR_MCP_TOKEN-YOUR_KEY"
CT="Content-Type: application/json"

# 1. initialize
curl -X POST "$BASE" -H "$AUTH" -H "$CT" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
        "params": {} }'

# 2. list the tools
curl -X POST "$BASE" -H "$AUTH" -H "$CT" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

# 3. run a search
curl -X POST "$BASE" -H "$AUTH" -H "$CT" \
  -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
        "params": { "name": "ask_yourbrand",
                    "arguments": { "question": "Rate outlook?" } } }'

const BASE = "https://api.askmiso.com/v1/ask/mcp";
const HEADERS = {
  Authorization: `Bearer ${MCP_TOKEN}-${API_KEY}`,
  "Content-Type": "application/json",
};

async function rpc(method, params = {}, id = 1) {
  const res = await fetch(BASE, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ jsonrpc: "2.0", id, method, params }),
  });
  return res.json();
}

await rpc("initialize");
const tools = await rpc("tools/list", {}, 2);
const hit = await rpc("tools/call", {
  name: "ask_yourbrand",
  arguments: { question: "What changed in the rate outlook?" },
}, 3);

import requests

BASE = "https://api.askmiso.com/v1/ask/mcp"
HEADERS = {
    "Authorization": f"Bearer {MCP_TOKEN}-{API_KEY}",
    "Content-Type": "application/json",
}

def rpc(method, params=None, id=1):
    body = {"jsonrpc": "2.0", "id": id, "method": method,
            "params": params or {}}
    return requests.post(BASE, headers=HEADERS, json=body).json()

rpc("initialize")
tools = rpc("tools/list", id=2)
hit = rpc("tools/call", {
    "name": "ask_yourbrand",
    "arguments": {"question": "What changed in the rate outlook?"},
}, id=3)

tools/list shows the two tools available to your app. If the search tool is missing, MCP is not yet enabled for your key.

Protecting your content

An MCP server gives an AI assistant access to your archive. Miso controls that access at four levels.

Snippets are not addressable

This is the main protection. The detail tool does not accept any product_id you choose. It only returns a snippet that a search already returned to you, and only for one hour after that search.

The result:

Nobody can enumerate your catalog by guessing or incrementing ids.
Nobody can walk through a whole article by stepping the offset.
Every full-text read must follow a real search that surfaced that exact passage.
Access to a passage expires one hour after the search that found it.

Bulk extraction therefore needs thousands of genuine searches. Each one is slow, is charged, and is recorded.

Miso records every refused read as well as every successful one. A client that probes for content it was never shown is visible in your usage data. See Usage and analytics.

Requests from data centers are blocked

Miso blocks traffic from cloud and hosting providers, from known scraper networks, and from selected regions. This stops most scripted extraction, because that traffic rarely comes from a home or office connection.

Rate limits and IP restrictions

Miso can cap how many MCP calls your app accepts, and can restrict MCP access to your own IP ranges. Both are useful when only your staff or one internal application uses the server. Contact your Miso representative to set them up.

Your credentials control access

Both an API key and your app's MCP token are required, and the token is specific to your app. If a credential leaks, ask Miso to rotate the token. Every client that uses it loses access immediately.

Treat the server URL as a secret. It carries both values.

Usage and analytics

Miso records every MCP call. Ask your Miso representative for a report, or for access to the usage data.

What Miso records

Call	What is stored
Search	The question, the optional `context` and `author`, the `skill_used` tag, and how long the call took.
Full-text read	The article id, the passage offset, whether the read was allowed, the size of the passage served, and a short excerpt of it.

Miso stores the length and a short excerpt of each passage it serves, not the whole passage.

What you can measure

Volume. Searches and full-text reads per day, and the trend over time.
What people ask. The questions assistants send to your content.
The read-through funnel. Miso links each full-text read back to the search that surfaced it. You can therefore measure how many searches lead to a read, and how many results an assistant reads per search.
Which content gets used. The articles that assistants read most, and how much of each one they read.
Refused reads. Attempts to fetch a passage that no search returned. A rise here suggests someone is probing your archive.
Speed. How long searches take for your catalog.

Tag your own traffic

Pass skill_used on any call to label where it came from — a named workflow, a prompt template, or one internal application. Miso records the value, so you can split your usage report by it.

{
  "name": "ask_yourbrand",
  "arguments": {
    "question": "What changed in the rate outlook?",
    "skill_used": "morning-briefing"
  }
}

One limitation

MCP reporting is per app, not per person. MCP clients do not send an end-user identity, so Miso cannot break usage down by seat or by reader. If you need per-user reporting, talk to your Miso representative about the options.

Notes and limits

Errors return HTTP 200. JSON-RPC reports failures in the response body, not in the status code. Read the error field, and read isError on a tool result.
Both tools are read-only. They carry the read-only annotation, so clients can let a user approve them once.
Search takes a few seconds. Half of searches complete in about 6 seconds. Reading a snippet is almost instant.
Results are scoped to your catalog. The assistant cannot reach content outside it.
One URL serves every brand. Your API key decides which brand's tool appears, so keep your key and token together.

Search & Recommendation

MCP — for your Subscribers