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.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- forgetful-cli-setupSkill
- forgetful-context-gatherSkill
- forgetful-encode-repoSkill
- forgetful-entitiesSkill
- forgetful-exploreSkill
- forgetful-filesSkill
- forgetful-proceduresSkill
- forgetful-recallSkill
- forgetful-rememberSkill
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
- Very specific: line 18
Every MCP client sees the same three tools fronting the full registry: discover_forgetful_tools (what exists, by category), …
- Very specific: line 62
After upgrading, api-only token users must add appropriate tool scopes at the issuer and obtain new tokens or update introspection …
- Very specific: line 82
Run Forgetful MCP calls in the main conversation — subagents do not inherit MCP tool access.
≈ “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.
Files
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(equivalentlyforgetful 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 # HTTPOther 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:
discover_forgetful_toolsreturns categories, and they match the server's enabled feature flags (skills/files/plans appear only when enabled).- One
execute_forgetful_toolround-trip returns real data —get_current_userorlist_projectsboth 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).
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
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.

