@vayacore/mcp

@vayapin/mcp

Model Context Protocol server for VayaPin. Gives any MCP-compatible agent (Claude Desktop, Cursor, n8n, Zapier, …) VayaPin pin resolution plus Google Maps and AfterShip tools through a single tool namespace, authenticated with a Personal Access Token.

Status: v0.1.0 — published to the VayaPin Verdaccio registry (https://npm.vayapin.app). Ships 8 P1 tools over one MCP namespace: resolve_pin, preview_pin, confirm_pin (VayaPin), geocode, reverse_geocode, place_search, place_details (Google Maps via BYOK proxy), and track_package (AfterShip via BYOK proxy), plus a system_health sanity tool.

Install

@vayapin/mcp lives on the VayaPin registry (https://npm.vayapin.app) and is public — no registry token needed. Map only the @vayapin scope to that registry (its dependencies resolve from the public npm registry as usual). Add one line to your .npmrc:

# .npmrc
@vayapin:registry=https://npm.vayapin.app

Then install or run it like any package:

npm install @vayapin/mcp        # into a project
npx -y @vayapin/mcp             # no install

Don't point your default registry at npm.vayapin.app (npm install --registry https://npm.vayapin.app …). That routes this package's dependencies through the private registry too, which requires auth — only the @vayapin scope is public. The scoped .npmrc line above is the supported path. (A VAYAPIN_PAT is still required at runtime to call the API — see below.)

Configure (MCP client config)

Add the @vayapin scope line to your ~/.npmrc (above) so npx can resolve the package, then:

{
  "mcpServers": {
    "vayapin": {
      "command": "npx",
      "args": ["-y", "@vayapin/mcp"],
      "env": {
        "VAYAPIN_PAT": "vayapin_pat_..."
        // optional: "VAYAPIN_MCP_SLICE": "<slice-name>"
        // optional: "VAYAPIN_MCP_API_URL": "https://api.vayapin.app/api/v1"
      }
    }
  }
}

Generate a PAT on the VayaPin developer portal (POST /api/v1/auth/pat/request). A 401 at runtime means the token is missing/expired/revoked — regenerate it.

Environment variables

Var	Required	Default	Purpose
VAYAPIN_PAT	yes	—	Personal Access Token, sent as Authorization: Bearer.
VAYAPIN_MCP_SLICE	no	—	Name of a tool slice to expose (see ceiling lift). Unset → all tools.
VAYAPIN_MCP_API_URL	no	https://api.vayapin.app/api/v1	Override for staging / self-host.

The 128-tool ceiling lift — how it works, and why this shape

Many MCP clients inject the entire tool list into the model's system prompt on every turn. Past roughly 128 tools some clients (Claude Desktop, Cursor, Antigravity, certain OpenAI Responses deployments) silently drop the tool injection or burn a large slice of the context budget. A server that naively registers its whole catalog breaks for those clients as it grows.

@spideriq/mcp solved this and we port its pattern verbatim rather than invent a new one. The two halves of its solution:

• Named tool-slice allowlist, selected by an env var (implemented here). The full catalog is assembled internally, but an env var (SPIDERIQ_MCP_SLICE there; VAYAPIN_MCP_SLICE here) names a frozen allowlist of tool names, and the server exposes only that slice. SpiderIQ ships a mac-128 slice (~123 tools) for exactly this reason.
• Atomic per-product packages (deferred; not needed at 8 tools). SpiderIQ also publishes @spideriq/mcp-publish, -mail, -leads, etc. — each a thin wrapper that registers only its product's slice, with tool implementations shared from one private package. We keep tools as data objects in group modules (src/tools/*.ts) so this split is available later without rework.

Mechanism (this package)

• The server uses the low-level Server API with manual ListTools / CallTool handlers — not the high-level server.tool() helper. This is what lets us control exactly which tools are advertised.
• Tools are plain data: { name, description, inputSchema, execute } (src/tools/types.ts). The MCP layer never sees execute.
• Tool groups register into a catalog via register() / registerAll() (src/tools/registry.ts), wired from the append-only aggregation point src/tools/index.ts.
• At boot, applySlice(catalog, VAYAPIN_MCP_SLICE) filters the catalog. Both ListTools and CallTool operate on the filtered set, so a hidden tool is neither listed nor callable (calling one returns MethodNotFound).
• No slice set → full catalog. Unknown slice name → full catalog + a stderr warning (fail-open, mirroring SpiderIQ).

Note — no "meta-tool". An earlier hypothesis was a single runtime list_tools meta-tool. SpiderIQ does not do that; it uses static named slices. We match SpiderIQ. The ceiling-lift proof lives in tests/registry.test.ts ("ceiling lift" describe block): 200 stub tools + a 100-tool slice ⇒ exactly 100 exposed.

Adding a tool (for tasks 4.2 / 4.3 / 4.4)

• Create src/tools/<group>.ts exporting <group>Tools(client): ToolDefinition[]. Copy src/tools/system.ts as the template.
• Add one import + one registerAll(<group>Tools(client)) line to src/tools/index.ts (append-only — the Orchestrator union-merges this file).
• Add a test under tests/.

Use snake_case tool names per VayaPin Product Definition v10 §6.1. Keep descriptions one line — they cost context on every client turn.

Layout

src/
  server.ts          entrypoint — boots Server over stdio, wires the registry
  auth.ts            PAT loading + Bearer header (no token logging, no auto-refresh)
  api/client.ts      undici HTTP client for api.vayapin.app/api/v1 (structured errors)
  tools/
    types.ts         ToolDefinition + JSON-Schema types (spec §6.1)
    registry.ts      catalog + named-slice ceiling lift + ListTools/CallTool wiring
    index.ts         append-only tool aggregation point
    system.ts        system_health tool (canonical example group)
tests/               vitest: registry (ceiling), auth, api client, server boot

Develop

npm ci
npm run build           # tsc → dist/
npm test                # vitest
npm test -- registry    # just the ceiling-lift proof