agentleFS
ScottRBKScottRBK/forgetful/skills/forgetful-mcp-setup/SKILL.md

forgetful-mcp-setup

Skill341 starsChanged 23 days agoMITView on GitHub

Set up an MCP client for Forgetful — wire Claude Code, Cursor, Copilot, Codex, Gemini, or OpenCode to the server and verify the connection behaves. Covers stdio vs HTTP transport, auth and scopes, the three meta-tools every client sees, and delegation to subagents.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every MCP client sees the same three tools fronting the full registry: discover_forgetful_tools (what exists, by category), …

    line 18
  2. Very specific:

    After upgrading, api-only token users must add appropriate tool scopes at the issuer and obtain new tokens or update introspection …

    line 62
  3. Very specific:

    Run Forgetful MCP calls in the main conversation — subagents do not inherit MCP tool access.

    line 82

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Setting up an MCP client

Every MCP client sees the same three tools fronting the full registry: discover_forgetful_tools (what exists, by category), how_to_use_forgetful_tool (one tool's docs and schema), execute_forgetful_tool (invoke by name with a JSON arguments object). Roughly 500 tokens of surface, with everything else disclosed at runtime.

Pick a transport

  • stdio — the client spawns the server per session: command uvx forgetful-ai (equivalently forgetful serve --transport stdio). Right for a personal, local setup.
  • HTTP — the client connects to a running server at <server>/mcp, e.g. http://localhost:8020/mcp. Right for a shared or deployed instance.

Claude Code, as the worked example:

claude mcp add forgetful -- uvx forgetful-ai                          # stdio
claude mcp add --transport http forgetful http://localhost:8020/mcp  # HTTP

Other clients follow the same two shapes (spawn command, or HTTP endpoint) in their own config format — full per-client walkthroughs live in docs/connectivity_guide.md in the Forgetful repo.

Optional feature discovery over HTTP

GET <application-base>/.well-known publicly reports enabled planning, skills, files, and activity streaming without creating a user. Keep any deployment prefix: for a server at https://host/forgetful/mcp, use https://host/forgetful/.well-known. These settings are not a health or permission check. Treat missing keys or unsupported schema versions as unknown, not disabled. See docs/api_reference.md for the capability document. MCP tool discovery is unchanged.

Auth and scopes

A local server defaults to no-auth single-user mode. Deployed servers use bearer tokens or OAuth. FASTMCP_SERVER_AUTH_*_REQUIRED_SCOPES controls IdP admission requirements. FORGETFUL_SCOPES sets the server's MCP/local CLI tool limit. Recognised scopes in verified token scope/scp claims can narrow MCP access further; they also apply to the remote CLI's MCP calls.

For JWT/introspection tokens, api:read api:write read can satisfy IdP requirements while allowing only read tools. openid read also stays read-only. Accepted Forgetful labels are *, read, write, read:<category> and write:<category>. A nonempty claim with no recognised label denies all MCP tools. Absent/empty claims retain server permissions after successful authentication.

After upgrading, api-only token users must add appropriate tool scopes at the issuer and obtain new tokens or update introspection responses. Changing REQUIRED_SCOPES alone does not change a token. Built-in GitHub/Google OAuth logins normally expose no scope claim to this resolver and retain the server permissions; do not request arbitrary Forgetful API scopes from those providers. See docs/configuration.md, "Authentication scopes and Forgetful tool permissions", for examples and upgrade steps. Do not assume MCP scope restrictions also protect REST endpoints.

Verify — the completion criterion

Behavioural, not configurational:

  1. discover_forgetful_tools returns categories, and they match the server's enabled feature flags (skills/files/plans appear only when enabled).
  2. One execute_forgetful_tool round-trip returns real data — get_current_user or list_projects both work as smoke calls.

Done when: both pass in the client that was just wired, in a fresh session.

Delegation boundary

Run Forgetful MCP calls in the main conversation — subagents do not inherit MCP tool access. When work must be delegated to a subagent, give it the CLI surface instead (Bash with the forgetful command travels into subagents; see forgetful-cli-setup).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.