@findagent/mcp

Run any FindAgent agent as a live MCP server — with zero agent code on your machine.

The trusted, declarative runtime for FindAgent agents. Point any Model Context Protocol client — Claude (Desktop / Code), ChatGPT, Gemini CLI, Cursor, VS Code, or your own — at a FindAgent agent and this package serves it over stdio.

A FindAgent agent is a manifest, not a program: it describes its tools (an HTTP call, a prompt template) and never ships executable code. This runtime is the single trusted layer that executes those declared bindings — so there is no remote-code-execution surface, ever.

Quick start

# Serve a marketplace agent (sign in once, then run by slug)
npx @findagent/cli login
npx -y @findagent/mcp run my-agent

# …or a local manifest
npx -y @findagent/mcp run --manifest ./my-agent.json

The server speaks MCP over stdio (stdout = protocol, stderr = diagnostics). Requires Node ≥ 18.

Connect it to a client

Add it to your client's MCP config (Claude Desktop / Cursor / VS Code — VS Code uses a servers key with "type": "stdio"):

{
  "mcpServers": {
    "my-agent": {
      "command": "npx",
      "args": ["-y", "@findagent/mcp", "run", "my-agent"]
    }
  }
}

The agent's tools appear as callable tools; its example prompts appear as MCP prompts with meaningful names + descriptions (never example-1). A tool-using agent never exposes its internal system prompt.

Commands

| Command | What it does | | --- | --- | | run --manifest <file> | Serve a local manifest over stdio. | | run <slug> | Fetch a marketplace agent's manifest and serve it (needs findagent login). | | run-department <dir> | Serve a downloaded Department (2–16 agents, up to 8 peer-to-peer) as one MCP server — the runtime handles agent-to-agent routing internally; to your client it's a single server. |

Credentials

A tool that needs a secret declares an auth_ref → a credential slot. You supply the value at runtime, resolved in order:

1. Env var FINDAGENT_CRED_<REF> (ref uppercased, non-alphanumerics → _; slot stripe_key → FINDAGENT_CRED_STRIPE_KEY).
2. Local store via findagent secrets set <ref> (a 0600 file shared with the CLI).

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

Each slot picks its auth scheme — bearer (default) · basic (Basic base64(id:token), e.g. Jira/Confluence) · raw (verbatim) · header (a custom header such as X-API-KEY). A slot may also bind to an install-time host (self-hosted GitLab/Jira/Metabase), taking its target host from your connect screen.

Security

The runtime executes only declared bindings — it never evals agent code. Every outbound call is hardened:

| Guard | Guarantee | | --- | --- | | Credential ↔ host binding | A secret attaches only when the request host matches the slot's allowed_hosts — never leaks to a third-party host, even if a tool URL points elsewhere. | | https-only + SSRF egress guard | Non-https rejected; the destination is DNS-resolved and blocked on any private / loopback / link-local / reserved / metadata (169.254.169.254) range — re-checked on every redirect hop. | | Manual redirects | Followed explicitly; Authorization (and a custom cred header) dropped on a cross-host hop. | | Auto-guardrail floor | A destructive tool auto-gets an approval:'human' gate before it runs (default ON) — resolved by interactive MCP elicitation ("Approve this action?"); if no one can be asked, it's refused. An explicit guardrail may only tighten it. | | Tool-order + secret-scan rails | A requires[] order rail gates a tool until its prerequisites have run; a mandatory output scan strips leaked secrets from results. | | Idempotency | Each Department member call gets a stable Idempotency-Key, so a re-run dedupes a true replay upstream. |

Tool annotations (readOnlyHint / destructiveHint / …) are advertised on tools/list and verified — a tool claiming readOnlyHint:true on a mutating verb is overridden, never trusted.

Library use

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

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

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; the token is only ever 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 | Destructive-tool approval floor (default ON; 0 to disable). |

Links

Marketplace findagent.cloud · Docs findagent.cloud/docs/connect · CLI @findagent/cli

License

MIT © FindAgent