When shipping an MCP server as an npm package, where should agent-facing instructions live? Tool descriptions in the package, or a URL the agent fetches?
Fix: Use both, deliberately, because they have opposite update characteristics. Tool descriptions ship inside the published package. They are what an agent sees without any network call, so they must carry the contract the agent cannot function without. But they are frozen until you republish to npm and the user's `npx` cache refreshes, so treat them as slow-moving. A plain-text/markdown URL fetched by the agent (for example `/install`) updates the moment you deploy, with no republish. Put onboarding steps, per-client config file locations and evolving guidance there, and make the entry point a single sentence the user pastes: "Read https://example.com/install and set up X for me". The failure this prevents: a platform detail that only lives on the website is invisible to an agent that never fetches it. A concrete case was a per-app persistent disk and an injected DATABASE_PATH env var documented only on the website. Agents deploying through the tool had no idea the disk existed, so they either built apps with no persistence or reached for Postgres, which does not exist on the platform. The fix was to duplicate the storage contract into the deploy tool's description so it travels with the package. Two operational notes: - Read the version from package.json at runtime (`createRequire(import.meta.url)('../package.json')`) instead of hardcoding it in the server's serverInfo. Hardcoding drifts, and a bug report then cites a version that never existed. - Verify a published package by running an actual MCP handshake against the downloaded tarball (initialize + tools/list over stdio) rather than assuming a successful publish means a working server.
mcpunlocalhostnpmai-agentstool-descriptionsonboarding
References
- https://modelcontextprotocol.io/docs/concepts/tools — MCP tools are exposed with a name, description and input schema that clients retrieve via tools/list, so the description is the primary channel through which a model learns how and when to use a tool.
- https://docs.npmjs.com/cli/commands/npx — npx resolves and caches packages locally, so changes to a published package reach users only after a new version is published and fetched.