best-practices-mcp

MCP server exposing a servicenow_search tool that searches mynow.servicenow.com — ServiceNow's public best-practices library/landing page — across content types (Best Practices, Product Documentation, Developer Portal docs, Now Community posts, and more).

No authentication required

mynow.servicenow.com is a public site — there's no login, token, or API key needed. It's not a traditional SSO-protected ServiceNow instance; it's a public-facing Now Experience app running in "Genius Search" / guest-session mode.

There's also no public, documented REST API for its search — it's reverse-engineered from a Playwright network capture of the site's own search UI (see scripts/probe.ts and src/servicenow/search.ts for the confirmed request/response shape). The flow:

1. GET any page on the site → returns a guest session cookie plus a CSRF token embedded in the HTML as window.g_ck.

2. POST /api/now/v1/batch, wrapping a GraphQL call to the site's Genius Search data broker, using that cookie + token.

3. Parse result[0].executionResult.output.data.GlideSearch_Query.search for results, facets, and total hit count.

This was confirmed with a cold, browser-free curl round-trip (no Playwright, no reused session) — genuinely unauthenticated, not just working because of a live browser session.

If search ever stops working, the site's frontend likely changed one of the fixed config IDs in src/servicenow/search.ts (SEARCH_DEFINITION_SYS_ID, SEARCH_CONTEXT_CONFIG_ID, SEARCH_EVAM_CONFIG_ID). Re-discover them with a fresh Playwright capture filtered to xhr/fetch traffic (write to a file, grep it — never dump raw capture output into a conversation) rather than guessing. Then re-run npm run probe to confirm.

Related MCP server: ServiceNow MCP Server

Development

npm install
npm run dev            # run the server directly with tsx (stdio transport)
npm run build           # compile to dist/
npm start                # run compiled dist/index.js
npm run probe -- "some query"   # verify the live search flow still works

Testing with MCP Inspector

npx @modelcontextprotocol/inspector npm run dev

Using with Claude Code / Claude Desktop

claude mcp add --scope user best-practices-mcp -- node "C:/dev/best-practices-mcp/dist/index.js"

No environment variables are required — SN_INSTANCE_URL defaults to https://mynow.servicenow.com and only needs overriding if pointing at a different instance.

Pagination

The API returns a fixed 10 rows per request and pages via an opaque paginationToken (base64 of an internal offset breadcrumb, e.g. offset:0,10). Use offset to page through the full corpus and limit to control how many rows you get back:

• offset is a row index into the full corpus (offset=10 → second page, offset=20 → third, etc.). It's implemented by constructing a token that jumps directly to that row — the server doesn't validate the breadcrumb, so any offset is random-accessible in a single request.

• limit (1–50) can exceed the 10-row page size; the server is paged internally (ceil(limit / 10) requests, following the API's own returned token after the initial jump) to gather that many rows.

• hasMore in the response is true when more results exist beyond offset + limit (offset + limit < totalResults).

Because the offset jump relies on the reverse-engineered token format, npm run probe exercises offset paging end-to-end — if the encoding ever changes, re-discover it from a fresh capture (see below) rather than guessing.

Downloading documents

Search itself needs no auth, but the actual file behind a file-backed result (presentations, workbooks, docs) is gated behind a real ServiceNow ID / Okta SSO login — confirmed live via Playwright (see scripts/probe-headed-login.ts).

1. servicenow_login (MCP tool) or npm run login (standalone script) — both open a real, visible browser window and save the resulting session to .auth/servicenow-storage-state.json (gitignored — this is a live credential) once you complete the ServiceNow ID / Okta login by hand. The MCP tool returns immediately — a headed browser waiting minutes on human SSO/MFA input has no business blocking a tool-call response — so poll servicenow_login_status to see when the capture finishes (or failed) and whether a session file currently exists on disk.

2. servicenow_download_document (MCP tool) — pass a servicenow_search result's url. Two mechanisms depending on content type, both starting from the same cookie-replayed <table>.do?...&XML record fetch (confirmed to accept cookie replay outside the browser):

   • Most content types (e.g. marketing decks, u_dotcom_gsdr): no browser needed at all — the record's own fields carry the real file location directly (often a separate public CDN, no ServiceNow auth needed for that hop).

   • Best Practices Library assets (u_x_snc_accel_asset_file_gsdr — this project's primary target content type): the record's own x_snc_nl_data_extr_file_content field carries the full extracted text of the underlying file (confirmed for both .docx and .pptx sources) — this is preferred, since it's what an agent actually wants and needs no browser at all. The response also includes sourceUrl (the human-facing asset page) for anyone who wants the original formatted file — just open it in your own browser and complete your own login, no need to go through this tool. Only when that field is empty does this fall back to the real file's binary bytes, which live behind a separate API (api.servicenow.com/bpl/v1/attachment/<id>) gated by a real Okta OAuth Bearer token minted client-side at click time. A short-lived headless browser (reusing the captured session, no new login) drives the actual download click to mint that token, then a plain fetch uses it to pull the file bytes — see scripts/probe-bpl-token-capture.ts for how this was confirmed. If the session is missing or has expired, either path returns a clear error telling you to call servicenow_login again — no path ever launches a browser other than the brief, automated one used to mint a Best Practices Library token.

Known limitations

• contentType filters client-side by matching the result's own table or content-type label — there's no separate discovery tool for valid values yet. An unfiltered search's results carry their own table/contentTypeLabel, which is enough to learn valid filters organically; contentTypeFilters in the response also lists all available content types with live counts for the current query.