# Forgetful MCP Setup

> 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.

- Skill: `scottrbk/forgetful-mcp-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add scottrbk/forgetful-mcp-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/scottrbk/forgetful-mcp-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: scottrbk (https://skillmd.com/u/scottrbk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/scottrbk/forgetful-mcp-setup

---


# 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:

```bash
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.

## Auth and scopes

A local server defaults to no-auth single-user mode — connect and go. Deployed servers use
bearer tokens or OAuth (the server's configured provider). `FORGETFUL_SCOPES` on the server
side sets a capability ceiling (e.g. read-only) that both MCP and CLI honour; a client that
should only recall can be scoped so writes are refused.

## 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`).