ByteAsk Embedded MCP

The open-source MCP server behind ByteAsk Embedded Docs: a source-grounded, page-cited evidence-retrieval server for coding agents (Claude Code, Codex, Cursor) that write firmware / driver / protocol code and need exact facts — SunSpec points, register offsets, Modbus function codes, trip thresholds, SCPI commands, API symbols.

It returns verbatim snippets with page citations — never an authored answer — and when nothing is relevant enough it says no match rather than fabricate. Every document is treated equally (no authority/trust layer, no filters).

What's in this repo: the MCP server — tools, transports (stdio + Streamable HTTP), bearer auth, DNS-rebinding protection, and result rendering — plus a small, pluggable retrieval interface.

What's not in this repo: the retrieval engine and the document corpus. How documents are parsed, chunked, embedded, and ranked, and the licensed source material itself, sit behind the SearchBackend seam and power the hosted endpoint at https://mcp.byteask.ai/mcp. This repo ships an in-memory SampleBackend (a few illustrative, public-knowledge records) so the server runs out of the box.

The official hosted server

You don't need to run anything to use ByteAsk Embedded Docs — there's a hosted server with the full licensed corpus behind it. It gives Claude Code, Codex, Cursor, and any MCP client exact, page-cited facts from embedded and firmware reference docs: register maps, protocol function codes, SCPI commands, standard thresholds, datasheet specs. The guarantee is verbatim source, or "no match" — never an invented value.

• Name: byteask-embedded-docs

• Endpoint: https://mcp.byteask.ai/mcp (Streamable HTTP)

• Docs & per-client setup: https://docs.byteask.ai/embedded

claude mcp add --transport http byteask-embedded-docs https://mcp.byteask.ai/mcp

See Connect a client below for Cursor / Codex and the local build. This repository is the open-source server that powers that endpoint.

Related MCP server: RAG Information Retriever

The tools

Two retrieval tools plus a request tool. Input is natural language (or an exact identifier). Output is compact markdown.

• search_docs(query, limit=8) — search the corpus; return ranked evidence. Each hit: document title, a section + page citation, the verbatim snippet, and a result_id. A "no confident match" response means not found — do not fabricate.

• get_context(result_id) — expand a hit to its full source section.

• request_document(request) — ask for a missing document to be added (logged server-side).

Example output:

## Results for "what Modbus function code writes multiple registers"

### Sample — Modbus Application Protocol (illustrative) — §6.12, p.30
> Function code 16 (0x10), Write Multiple Registers, writes a block of contiguous
> holding registers (1 to 123 registers) in a remote device. ...
_ref: sample:modbus-fc16_

Quickstart (local)

Requires Python ≥ 3.10 and uv.

uv sync
uv run byteask-embedded-mcp            # run as an MCP server (stdio)

That's it — the bundled SampleBackend serves a couple of illustrative records, so search_docs works immediately. uv run pytest runs the offline tests.

Connect a client

Hosted endpoint (no install)

The hosted server speaks Streamable HTTP at https://mcp.byteask.ai/mcp:

claude mcp add --transport http byteask-embedded-docs https://mcp.byteask.ai/mcp

Or via the mcp-remote bridge (Codex, Cursor, …):

{ "mcpServers": { "byteask-embedded-docs": {
  "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.byteask.ai/mcp"] } } }

Local (this repo)

The project-scoped .mcp.json registers the stdio server for clients that read it. Manually, for Claude Code:

claude mcp add byteask-embedded-docs -- uv run byteask-embedded-mcp

Plug in your own retrieval

The server depends only on a two-method interface (backend.py):

class SearchBackend(Protocol):
    def search(self, query, limit=8, effort=None) -> dict: ...
    def get_context(self, result_id, effort=None) -> dict: ...

Implement it, expose a factory make_backend(config) -> SearchBackend, and point the server at it:

BYTEASK_BACKEND="my_pkg.my_module:make_backend"

The exact return-value contracts are documented at the top of backend.py.

Running over HTTP

MCP_TRANSPORT=http MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32) \
  uv run byteask-embedded-mcp --host 0.0.0.0 --port 8000

Clients then send Authorization: Bearer <token>. The bundled bearer check is a shared-secret stub — replace it with real auth (OAuth 2.1 resource server, mTLS, or a trusted reverse proxy) before exposing publicly. DNS-rebinding protection stays on independently via MCP_ALLOWED_HOSTS.

Configuration (.env, all env-overridable)

See .env.example.

Project layout

src/byteask_embedded_mcp/
  server.py     # FastMCP app + 3 tools (search_docs, get_context, request_document)
  backend.py    # SearchBackend protocol + in-memory SampleBackend (swap for real retrieval)
  render.py     # structured result -> compact markdown
  http_auth.py  # Streamable HTTP entrypoint + stub bearer-token guard
  config.py     # server config (transport, logging, backend selection)
  schemas.py    # Hit / Section result types
  obs.py        # per-call JSONL logging
tests/          # offline unit tests (renderer, backend, server tools)

Security notes

• stdout stays clean in stdio mode (it is the JSON-RPC channel); all logs go to stderr / logs/*.jsonl.

• The HTTP bearer check is a stub — unauthenticated if no token is set, and a shared secret at best. Harden it before exposing widely.

• DNS-rebinding protection is on by default for the HTTP transport.

License

MIT — see LICENSE.