# SignalBase: automatic setup for Codex and Claude Code

## Three steps for you

1. Open **Codex or Claude Code** and attach this Markdown file.
2. Send: **“Follow this guide to configure SignalBase on this computer and open the sign-in page.”**
3. In the browser, enter the **library username and temporary password** provided privately by your administrator. On first sign-in, choose a new password with at least **12 characters**, then approve access.

If you already changed your password on another client, use that new password.
Your library account is separate from your OpenAI or Claude account.

- MCP server: `https://signalbase.fans/mcp`
- Expected identity service: `https://xuanagent.com/auth/realms/research`

The xuanagent.com sign-in page is expected: SignalBase currently uses that existing identity service.

Once connected, try:

> Using only SignalBase, list the five latest Bernstein reports with their dates, titles and authors.

The remaining instructions are for the AI doing the setup.

---

## Instructions for the configuration agent

Configure a user-level Streamable HTTP MCP named `signalbase` on the current computer. Complete browser OAuth and verify the available tools. This authorizes changes to this MCP configuration only, not other connectors, accounts or projects.

### Identify the current client

- In Codex, configure Codex. In Claude Code, configure Claude Code.
- Do not modify both just because both are installed.
- Use available shell/file tools, not simulated typing into a terminal through computer-use tools.
- If the required tools are unavailable, give the user the minimum corresponding manual steps. Do not claim success.
- Let the user enter credentials in the browser. Never request passwords in chat, put them in commands/configuration, or save them to logs or Git.

### Codex

Inspect existing MCP configuration and `codex mcp --help`. Use the actual user configuration path, normally `~/.codex/config.toml`.

Back up the file, then merge only these two tables. Preserve all unrelated settings. Do not create duplicate TOML tables or change global callback settings.

```toml
[mcp_servers.signalbase]
url = "https://signalbase.fans/mcp"
startup_timeout_sec = 30
tool_timeout_sec = 180

[mcp_servers.signalbase.oauth]
client_id = "research-codex"
callback_url = "http://127.0.0.1:8767/callback"
callback_port = 8767
```

This is a pre-registered public client. No client secret, API key or bearer token is needed.

```text
codex mcp get signalbase
codex mcp login signalbase
```

Let the user finish sign-in, first-time password change and consent in the browser. If the browser does not open, provide the login URL generated by this command; do not construct one yourself. Do not print or save callback URLs containing authorization codes.

If tools are not visible in the running app, ask the user to refresh/restart the MCP connection or open a new task. Do not terminate unrelated active work. If `codex` is not on PATH, check for the CLI bundled with the installed application before assuming it is missing.

### Claude Code

Check `claude mcp get signalbase` first. If it exists, verify its URL, client ID and callback port. Modify only this entry if necessary; preserve other connections.

```text
claude mcp add --scope user --transport http --client-id research-claude-code --callback-port 8768 signalbase https://signalbase.fans/mcp
claude mcp login signalbase
```

If this version has no `mcp login` command, have the user enter `/mcp` inside Claude Code, select `signalbase`, then **Authenticate**.

Let the user complete sign-in and consent in the browser. If the version does not support `--client-id` or `--callback-port`, explain that Claude Code needs updating (`claude update`). Do not remove these options to work around the issue. Leave Client Secret empty and do not substitute another platform's client ID.

### Verify

1. Confirm that the connector no longer reports “Needs authentication.”
2. Confirm three tools: `query_catalog`, `search_content`, `read_document`.
3. Run the sample Bernstein report question through the actual catalog tool.
4. Report configuration, sign-in and tool verification separately. If this task cannot reload MCP tools, say that a new task must verify the tool call; do not claim it was executed.

### Common situations

- **First password change:** minimum 12 characters; all clients share the new library password.
- **New computer:** repeat setup and authorization; local credentials usually do not sync automatically.
- **Old Research Library connection:** add `signalbase` and keep the old connection until the new one works. Explicitly select SignalBase when querying.
- **Busy callback port:** Codex uses 8767; Claude Code uses 8768. Report the conflict. Do not kill unknown processes or choose arbitrary ports.
- **Expired sign-in:** authorize again; rebuilding the entire configuration is unnecessary. Current ordinary session idle/absolute limits are 12 hours, with short-lived access tokens refreshed automatically.
- **Troubleshooting:** share client version, time and error text with the administrator, not passwords, tokens or authorization-code URLs.

Official references: [Codex MCP](https://developers.openai.com/codex/mcp), [Claude Code MCP](https://code.claude.com/docs/en/mcp).

Guide date: 2026-09-14.