Build an MCP Search Tool with Prismfy

This tutorial focuses on a production-friendly search integration pattern, so developers can add a web search tool, fresh public evidence, and better routing logic without overbuilding retrieval.

Problem framing

MCP works best when tools are narrow and well named. A search tool should search. It should not pretend to be a browser, a scraper, or a full agent platform.

Prismfy fits that boundary. Your MCP tool can take a natural-language query, send one POST /v1/search request, and return a compact evidence set that the model can reason over. That gives the assistant current public context without pushing retrieval logic into the prompt.

This is especially useful for questions that depend on changing public pages: docs, changelogs, release notes, pricing pages, and company pages.

Why this matters now

Models are strongest when the evidence layer is explicit. An MCP tool is one of the cleanest places to make that explicit because the client already expects structured inputs and outputs.

If you skip the search layer, the model will try to answer from memory. If you make the tool too broad, it becomes hard to debug. A single-purpose search tool is usually the right middle ground.

Step-by-step solution

The pattern is simple.

1. Define one MCP tool called something like prismfy_search.
2. Accept a query and a small set of optional filters.
3. Call Prismfy through POST /v1/search.
4. Trim the result set to the top few sources.
5. Return titles, URLs, snippets, and minimal metadata.

The model can then cite those sources or ask for a narrower query if the results are weak.

Code example

The following TypeScript example shows the core of the tool handler. It uses plain fetch, so the boundary stays visible.

type PrismfyResult = {
  title: string
  url: string
  content?: string
}

type PrismfyResponse = {
  results: PrismfyResult[]
  cached?: boolean
  meta?: Record<string, unknown>
}

const PRISMFY_BASE_URL = process.env.PRISMFY_BASE_URL ?? "https://api.prismfy.io"
const PRISMFY_API_KEY = process.env.PRISMFY_API_KEY ?? ""

export async function prismfySearch(query: string, domain = "", timeRange = "week") {
  const payload: Record<string, unknown> = { query, page: 1, timeRange }
  if (domain) payload.domain = domain

  const response = await fetch(`${PRISMFY_BASE_URL}/v1/search`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${PRISMFY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  })

  if (!response.ok) {
    throw new Error(`Prismfy search failed with ${response.status}`)
  }

  const data = (await response.json()) as PrismfyResponse
  return {
    cached: data.cached ?? false,
    results: (data.results ?? []).slice(0, 4).map((item) => ({
      title: item.title,
      url: item.url,
      snippet: (item.content ?? "").slice(0, 180),
    })),
  }
}

In your MCP server, the tool definition can call prismfySearch and return the small object it produces. The exact SDK boilerplate will vary by package version, but the retrieval contract stays the same.

If you want a simple input schema, keep it close to the API:

• query for the user’s question
• domain when one source owns the truth
• timeRange when recency matters

That is enough for most live-evidence cases.

Practical notes and caveats

Keep the tool output short. MCP is a structured interface, but that does not mean you should pass the entire upstream payload through untouched. The model rarely needs everything. It needs enough evidence to answer or enough evidence to explain why it cannot.

Use domain when the answer should come from one public source. Use timeRange when the question is about current status or recent change. If the assistant asks for a broad web sweep, keep the result count low and be clear that the output is a shortlist, not an archive.

Prismfy is not doing the conversation for you. It is only the retrieval step. The assistant still decides whether the evidence is sufficient and how to phrase the answer.

That separation matters because it keeps the tool simple enough to maintain. The more logic you hide inside the search layer, the harder it becomes to debug source selection and answer quality.

If you want to make the tool safer, add a tiny validation step before the Prismfy call. For example, reject blank queries, trim excessive whitespace, and cap any optional domain input to one host. Those checks are boring, but they prevent your tool from turning malformed input into noisy results.

It also helps to keep a stable response schema for the MCP client. Even if Prismfy returns richer metadata later, your tool can continue returning a small object with query, cached, and a short results array. That makes downstream prompts and tests much easier to maintain.

Why Prismfy fits this workflow

Prismfy fits MCP because it keeps retrieval synchronous and visible. One call goes out, one result set comes back, and the tool can expose exactly the information the model needs.

That makes it practical for assistants that need fresh public facts without turning the server into a crawler or a browser controller. The tool stays narrow, the evidence stays inspectable, and the model stays grounded.

FAQ

Why use a web search API instead of only a retriever?

A retriever is useful for indexed material you control. A web search API helps when the question depends on fresh public evidence, new pages, current docs, or time-sensitive changes that may not exist in your retriever yet.

What is the safest way to add MCP Search Tool?

Keep the integration narrow: route only freshness-sensitive questions to Prismfy, pass a compact evidence set back to the framework, and ask the model to answer from sources instead of memory.

Related Prismfy guides

• Prismfy + LangChain: When to Use Web Search Instead of a Retriever
• Prismfy + LlamaIndex: Use Fresh Web Evidence in RAG
• Add Real-Time Web Search to an OpenAI Agent Workflow with Prismfy

Try Prismfy

Create a Prismfy key, test POST /v1/search, and wire the search step into the workflow you care about first.