@findagent/mcp

Turn a FindAgent agent manifest into a live MCP server — safely, with no agent code ever running on your machine.

Declarative MCP runtime for FindAgent agents. Turns a FindAgent agent manifest into a live Model Context Protocol server that any MCP client — Claude Desktop, Cursor, Claude Code, or your own — can connect to.

FindAgent agents are declarative-only: an agent is a manifest that describes its tools (an HTTP call, a prompt template), it never ships executable code. This package is the single trusted runtime that executes those declared bindings. No agent code runs on your machine — so there is no remote-code-execution surface.

What is FindAgent?

FindAgent is a cross-LLM marketplace for AI agents. Agents describe what they do in a manifest; this runtime is the trusted layer that runs them. Install an agent with the FindAgent CLI, then run it here as an MCP server your client connects to.

Install

Run it on demand with npx (no global install needed):

npx -y @findagent/mcp run --manifest ./my-agent.json

Or install it:

npm i -g @findagent/mcp
findagent-mcp run --manifest ./my-agent.json

Requires Node.js ≥ 18.

Usage

Run a local manifest

findagent-mcp run --manifest <path-to-manifest.json>

The server speaks MCP over stdio — that's what MCP clients expect. All diagnostics go to stderr; stdout is the protocol channel.

Run a marketplace agent by slug

findagent-mcp run <slug>

This fetches the agent's published manifest from the marketplace. The endpoint is auth-gated, so sign in first with the FindAgent CLI:

npx @findagent/cli login        # stores a token
findagent-mcp run my-agent      # uses it automatically

(or set FINDAGENT_TOKEN yourself).

Run a Department

A Department is 2–8 marketplace agents composed into a team. Download one with the CLI, then serve the whole team as a single MCP server:

npx @findagent/cli download growth-crew-a1b2c3   # writes the bundle locally
findagent-mcp run-department ./growth-crew-a1b2c3

The runtime handles the agent-to-agent routing internally; to your client it's one server.

Commands

| Command | What it does | | --- | --- | | findagent-mcp run --manifest <file> | Serve a local manifest as an MCP server over stdio. | | findagent-mcp run <slug> | Fetch a marketplace agent's manifest and serve it (requires findagent login). | | findagent-mcp run-department <dir> | Serve a downloaded Department as one MCP server. |

Connect it to an MCP client

Point any MCP client at the run command. For Claude Desktop / Cursor, add to the MCP servers config:

{
  "mcpServers": {
    "my-agent": {
      "command": "npx",
      "args": ["-y", "@findagent/mcp", "run", "--manifest", "/abs/path/to/my-agent.json"]
    }
  }
}

The agent's tools appear in the client as callable tools, and its system prompt + example prompts are exposed as MCP prompts — so every FindAgent agent is connectable, recipe or tool-using.

Credentials

A tool whose action needs a secret declares an auth_ref pointing at a credential slot. You supply the secret at runtime — it is resolved in this order:

1. Environment variable FINDAGENT_CRED_<REF> — the ref uppercased, non-alphanumerics replaced with _. E.g. slot stripe_key → FINDAGENT_CRED_STRIPE_KEY.
2. Local credential store written by findagent secrets set <ref> (a 0600 credentials.json in your OS config dir), shared with the FindAgent CLI.

# either:
export FINDAGENT_CRED_STRIPE_KEY=sk_live_...
# or:
npx @findagent/cli secrets set stripe_key

A resolved secret is only ever sent to the host(s) the slot's manifest allows (allowed_hosts) — never to a third party, even if a tool's URL points elsewhere. Secrets are never logged.

Security

The runtime executes only the declared binding kinds; it never evals agent-supplied code. The HTTP executor is hardened:

• https-only — non-https action URLs are rejected.
• Egress guard — the destination is DNS-resolved and rejected if it points at a private / loopback / link-local / unique-local / reserved / carrier-grade-NAT range or cloud metadata (169.254.169.254), re-checked on every redirect hop (SSRF defense).
• Credential ↔ host audience binding — a slot's secret attaches only when the request host matches the slot's allowed_hosts; otherwise the request goes out with no credential.
• Manual redirects — redirects are followed explicitly and the Authorization header is dropped on a cross-host hop.
• Caps — request timeout and a response-body size cap.

Tool annotations & the auto-guardrail floor

Every served tool advertises MCP annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint) on tools/list, so a connecting client (Claude etc.) can decide auto-run vs confirm. The annotations are derived from each tool's action (HTTP GET→read-only, DELETE→destructive, …) and verified — a tool that claims readOnlyHint:true on a mutating verb is overridden, never trusted. Forwarding annotations is always on and is safe (they are advisory hints).

Set MCP_TOOL_ANNOTATION_ENFORCE=1 to also have the runtime auto-attach a guardrail floor (approval:'human') to any tool whose annotations say destructive or not-read-only, before it executes — so confirmation no longer depends on the creator hand-writing guardrails.actions. An explicit guardrails.actions entry may only tighten (an explicit approval:'none' on such a tool is raised to the floor; it can never loosen below it). A read-only tool is never floored.

The flag is OFF by default (dark-launchable): with it off, annotations are still forwarded but no floor is auto-attached, so already-published read-only-in-practice agents are not surprised by new confirmation prompts. The floor is derived from the manifest at serve time — it is not retroactive to stored data.

Environment variables

| Var | Purpose | | --- | --- | | FINDAGENT_CRED_<REF> | Supply a tool credential by slot ref. | | FINDAGENT_TOKEN | Auth token for run <slug> (set by findagent login). | | FINDAGENT_BASE_URL | Override the marketplace host (self-hosted / preview). The token is only sent to a findagent.cloud host. | | FINDAGENT_LLM_API_KEY | LLM key used by run-department for agent-to-agent orchestration. | | MCP_TOOL_ANNOTATION_ENFORCE | 1/true to auto-attach an approval:'human' guardrail floor to destructive / non-read-only tools before execution (default OFF — annotations are still forwarded either way). |

Library use

The package also exports the engine, if you want to embed it:

import {
  startStdioServer,
  buildServer,
  executeToolAction,
  loadManifestFromFile,
  fetchManifestBySlug,
  defaultCredentialResolver,
} from '@findagent/mcp'

const manifest = await loadManifestFromFile('./my-agent.json')
await startStdioServer(manifest, defaultCredentialResolver())

Links

• Marketplace — https://findagent.cloud
• Docs — https://findagent.cloud/docs/connect
• CLI — @findagent/cli
• Support — https://findagent.cloud

License

MIT