Set up the MCP server

This walks you through connecting an MCP client (Claude Code, Claude Desktop, etc.) to your Simple Hello portal.

1. Generate a token

Open the portal → Settings → MCP tokens → New token.
Give it a name (e.g. "Laptop" or "Onboarding repo").
Check the projects this token should access — the token can never see flows outside that list.
Click Generate token, then copy the displayed token immediately. It's only shown once.

Tokens look like shmcp_<32 hex chars>. They inherit your role on each project, so a viewer's token can read but not edit.

2. Build the server

The server lives in the mcp/ folder of the portal repo.

cd portal/mcp
pnpm install
pnpm build

This produces dist/index.js, which is what your MCP client will run.

3. Add it to your MCP client

Most clients use an mcp.json (or equivalent) config file. Add an entry like:

{
  "mcpServers": {
    "simplehello": {
      "command": "node",
      "args": ["/absolute/path/to/portal/mcp/dist/index.js"],
      "env": {
        "SIMPLEHELLO_URL": "http://localhost:3000",
        "SIMPLEHELLO_TOKEN": "shmcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart the client. Ask the assistant something like "plan a user onboarding flow with email verification" — it should offer to visualize before writing any code.

4. (Optional) narrow this instance further

If your token already allows projects A, B, and C but you want this particular MCP instance to only see one of them, add an extra env var:

"env": {
  "SIMPLEHELLO_URL": "http://localhost:3000",
  "SIMPLEHELLO_TOKEN": "shmcp_…",
  "SIMPLEHELLO_PROJECT_ID": "abc123"
  // or: "SIMPLEHELLO_TEAM_ID": "xyz789"
}

This is a further narrowing — it never grants access the token doesn't already have. Useful when you have one token across several projects but want each editor or repo to see only its own.

Environment variables

Var	Required	Notes
`SIMPLEHELLO_URL`	yes	Portal base URL (e.g. `http://localhost:3000`).
`SIMPLEHELLO_TOKEN`	yes	Token from Settings → MCP tokens.
`SIMPLEHELLO_PROJECT_ID`	no	Restrict this instance to one project.
`SIMPLEHELLO_TEAM_ID`	no	Restrict this instance to one team (ignored if `SIMPLEHELLO_PROJECT_ID` is set).

Troubleshooting

Token has been revoked — the token is gone from Settings → MCP tokens. Generate a new one.
Token does not allow project <id> — your token's allowlist doesn't include that project, or you've been removed from it. Edit the token or use one with broader scope.
The assistant doesn't offer to visualize. Make sure the MCP server is actually connected (most clients show a status indicator) and that your prompt is non-trivial enough to trigger it. You can also just say "draw this as a Simple Hello flow".
last_used_at never updates. The portal writes it fire-and-forget after every authenticated call; if it stays empty, the request never reached the server — check the URL and that the portal is running.

Set up the MCP server#

1. Generate a token#

2. Build the server#

3. Add it to your MCP client#

4. (Optional) narrow this instance further#

Environment variables#