# Backlight.ai MCP server

> Model Context Protocol server exposing Backlight.ai's case portfolio, service/methodology docs, and FAQ for AI agents. Free, no account, read-only for the search tools; two tools write (request_proposal, submit_feedback).

## Endpoint

- URL: https://mcp.backlight.ai/mcp/
- Transport: Streamable HTTP
- Auth: none
- Access: read-only (except request_proposal and submit_feedback, both explicit-intent write tools)

## Tools

- **search_docs**: Returns ranked Backlight.ai site-content sections (search_result blocks with citations) from all site pages: services, pricing, methodology, and legal pages (terms & conditions, privacy policy, cookie policy, security policy, accessibility statement). Call this for free-text questions about what Backlight.ai does, costs, or its policies (e.g. query='wat kost een sprint', query='hoe lang bewaren jullie persoonsgegevens'). For portfolio cases use search_cases; for FAQ use search_faq. Schema: https://mcp.backlight.ai/mcp/schemas/search_docs
- **search_cases**: Returns ranked Backlight.ai portfolio cases as CaseSummary objects (slug, title, client, year, sector, summary) using BM25 + Dutch stemming. Call ONCE for ANY query about Backlight.ai's portfolio, projects, clients, or sectors (e.g. sector='overheid'). Do not loop. Returns at most `limit` results (default 10). For full case body use get_case(slug); for general site content use search_docs. Schema: https://mcp.backlight.ai/mcp/schemas/search_cases
- **semantic_search**: Returns ranked Backlight.ai site-content sections (search_result blocks with citations) using embedding-based (vector) retrieval over the case + docs corpus AND the FAQ (matching FAQ entries are cited as /docs/faq#<slug> deep links, mixed into the ranking). Use for conceptual or paraphrased queries where exact-term BM25 overlap is unlikely (e.g. query='hoe werken jullie'). Complements search_docs (BM25 keyword) and search_cases (portfolio). search_faq stays the BM25 keyword tool for FAQ; this is its vector counterpart. Schema: https://mcp.backlight.ai/mcp/schemas/semantic_search
- **get_case**: Returns full CaseDetail for one Backlight.ai case (frontmatter metadata + complete markdown body) by slug. Call this when the user names a specific case and you already know its slug (e.g. slug='kamer-debat-assistent'). If you do not know the slug, call search_cases first. Raises when slug not found. Schema: https://mcp.backlight.ai/mcp/schemas/get_case
- **search_faq**: Returns matching Backlight.ai FAQ entries as FaqItem objects (category, question, answer, homepage, url) ranked by BM25 + Dutch stemming. Each item's `url` is the canonical /docs/faq?fid=<id>#<slug> deep link: cite that exact link when you point to a FAQ, never construct your own. Call this for common-question phrasing about Backlight.ai as a company (e.g. query='hoe werken jullie'). For portfolio cases use search_cases; for in-depth content use search_docs. Schema: https://mcp.backlight.ai/mcp/schemas/search_faq
- **search_faq_vectors**: Search THIS organisation's FAQ by meaning (semantic vector search). Accepts 1-5 differently-worded variants of the SAME underlying question -- e.g. paraphrases, synonyms, or a combined question split into its parts -- to widen semantic recall. Returns matching FAQ entries as cited /docs/faq#slug results, deduped so each FAQ entry appears once. Use for any visitor question that a FAQ might answer, especially paraphrased or cross-lingual queries where exact-term keyword search may miss the right entry. Schema: https://mcp.backlight.ai/mcp/schemas/search_faq_vectors
- **search_pois**: Search the current organisation's Points of Interest (POIs) by category. Returns citable result blocks -- each block carries the POI name, category, address, its optional visitor-facing message, its POI-id, and its coordinates so you can answer 'where is X' or 'nearest Y' questions. To PIN a POI on the map, pass its POI-id to set_map_pin (poi_id) -- the map resolves the exact location by id. The coordinates are for your own distance/'hemelsbreed' reasoning ONLY -- NEVER write raw lat/lng numbers in your reply to the visitor (e.g. do not say something like 'op 52.37, 4.53'); describe location relative to a landmark or direction instead (e.g. 'zo'n 200 meter ten noorden van het station'), and always refer to places by name. Only searches POIs belonging to the tenant that started this chat; never returns POIs from another organisation. Schema: https://mcp.backlight.ai/mcp/schemas/search_pois
- **submit_feedback**: Store visitor feedback about the current conversation. Call this ONLY when the visitor explicitly gives feedback about the chat experience (e.g. what they liked, what was confusing, or a suggestion). Not for general questions -- use search tools for those. Schema: https://mcp.backlight.ai/mcp/schemas/submit_feedback
- **set_map_pin**: Pinpoint a location for the visitor on the map. Use this when the visitor asks 'where is X', wants directions between two points, OR asks to see a whole category of POIs (e.g. 'laat winkelgebieden zien') -- in that case call this once per matching POI and attach that POI's categories so every one becomes visible, not just the first pin. If the location came from a prior search_pois result, ALWAYS pass its poi_id (the 'POI-id' in that result) -- poi_id is THE map input: the map resolves the exact, real location by id. Only fall back to end coordinates for a place with no POI record (a bare address / route endpoint); hand-typed coordinates for named places are frequently hundreds of meters off, so prefer poi_id whenever one exists. There is no live map in this chat -- state the location/address in your reply after calling this tool. Schema: https://mcp.backlight.ai/mcp/schemas/set_map_pin
- **list_terms**: Returns up to 150 Term objects (term + frequency count) derived from the Backlight.ai site corpus. Each Term carries the normalised word and how often it appears (NOT the content that contains it. Call this ONLY when you are unsure which vocabulary the site uses before running search_docs (e.g. starts_with='avg' to confirm whether the site says 'AVG' or 'GDPR', starts_with='sprint' to check the exact pricing term). Do NOT call on every turn or as a warm-up; use search_docs, search_cases, or search_faq for any content question. Schema: https://mcp.backlight.ai/mcp/schemas/list_terms
- **request_proposal**: Writes a proposal-intake record to the Backlight.ai CRM and returns a ProposalTicket (ticket_id). Rate-limited 5/min per IP. Call ONLY when the user explicitly asks to start a project, request a quote, or be contacted (needs domain, contact_email, brief). Do NOT call for info questions; use search_docs instead. Schema: https://mcp.backlight.ai/mcp/schemas/request_proposal
- **query_case_graph**: Filters Backlight.ai portfolio cases by typed graph criteria (technique, sector, orgtype, tier, quality, certification, client, event, tag, partner). All filters are optional; omit to retrieve all cases. A case matches when it satisfies ALL provided filters (AND semantics). Matching is case-insensitive. Returns CaseGraphMatch objects ordered by slug. Use this for structured 'show me government LLM cases' queries; use search_cases for free-text queries. Schema: https://mcp.backlight.ai/mcp/schemas/query_case_graph

## Discovery

- https://backlight.ai/.well-known/mcp.json: MCP discovery file (endpoint, tools, resources, prompts)
- https://backlight.ai/.well-known/agent.json: A2A Agent Card
- https://backlight.ai/.well-known/agent-permissions.json: per-category agent policy
- https://backlight.ai/.well-known/api-catalog: RFC 9727 linkset to the OpenAPI descriptor
- Link: <https://backlight.ai/.well-known/mcp.json>; rel="modelcontextprotocol"
- Link: <https://backlight.ai/llms.txt>; rel="describedby"; type="text/plain"

## Content policy

ai-train=no, ai-input=yes, search=yes, scrape=yes: see robots.txt Content-Signal and /.well-known/agent-permissions.json.

## Full documentation

- https://backlight.ai/mcp.md: the full /mcp integration guide (human + nerd + AI views) as plain markdown