Skip to content

Use the MCP server

Reach the tools of the installed reefs from Claude Code or claude.ai: the Nereus API serves /mcp itself, each tool run as you, through the installation's entrance as /v1 is.

Before you start

  • An installation reachable at https://nereus.example.com, and nereus login done, from Turn on authentication.
  • To choose the tools the installation offers, a login in nereus-admins.

Steps

1. See the tools you may call

nereus mcp tool list shows each tool the installed reefs declare whose route you may call, the core's status first. A tool whose route is a POST shows off (write): it starts off until an admin enables it.

nereus mcp tool list
output
REEF           TOOL                STATE
core           status              on
presentations  presentations_list  on

2. Choose the tools the installation offers

An admin turns tools off or on with nereus mcp tool disable and enable, by name or every tool of a reef (<reef>_*). An exact name beats a pattern.

nereus mcp tool disable presentations_list
output
✓ tool presentations_list disabled for the instance
nereus mcp tool enable 'presentations_*'
output
✓ tools presentations_* enabled for the instance
! presentations_list stays off: disabled by its own name, which beats a pattern

The switch lives in the Installation's spec.mcp.tools; /mcp lists and calls only the tools on, and the list shows the others as off (instance). It is never changed through /mcp itself.

3. Add it to Claude Code

nereus mcp client add runs Claude Code's own claude mcp add, so it never writes the agent's settings or copies your token into them. --dry-run shows that command; --scope user, the default, adds the server to every project.

nereus mcp client add claude-code \
  --dry-run
output
would run: claude mcp add --transport http --scope user --client-id claude-code --callback-port 33418 nereus https://nereus.example.com/mcp
nereus mcp client add claude-code
output
✓ claude-code: MCP server nereus added (https://nereus.example.com/mcp, scope user, OAuth client claude-code)

Next steps:

  claude    # then /mcp, and log in to nereus

In Claude Code, /mcp opens the realm's login page in the browser.

4. Add it to claude.ai

In claude.ai, add a custom connector with the URL https://nereus.example.com/mcp and the OAuth Client ID claude. The client finds the issuer from the protected resource metadata (RFC 9728) and logs in with a token only /mcp accepts.

curl --silent https://nereus.example.com/.well-known/oauth-protected-resource/mcp
output
{"resource":"https://nereus.example.com/mcp","authorization_servers":["https://auth.example.com/realms/nereus"],"scopes_supported":["openid","offline_access"],"bearer_methods_supported":["header"]}

Check it worked

After the login, the Claude Code session lists the same tools as nereus mcp tool list. /mcp is stateless: a reef installed or uninstalled shows on the client's next connection. nereus mcp client list shows the coding agents that have it.

nereus mcp client list
output
CLIENT       SERVER  URL                             SCOPE
claude-code  nereus  https://nereus.example.com/mcp  user

Clean up

nereus mcp client remove claude-code
output
✓ claude-code: MCP server nereus removed

Next

Learn more

  • ADR 0029: each reef declares its tools in its Nereid's contract, and the Nereus API serves them.