# Run a local Diagnosis for an incident

Use a local client, such as Codex or Claude, with an MCP server that connects it to Tellagen. Then run an incident Diagnosis and review the saved result.

## Before you start

### Intended audience

Incident commanders and responders who investigate an active incident.

### Required permissions

You need an active responder seat. The Local Diagnosis preset includes incidents:read, incidents:write, slack_context:read, services:read, teams:read, and custom_fields:read.

### Local Diagnosis preset scopes

- incidents:read
- incidents:write
- slack_context:read
- services:read
- teams:read
- custom_fields:read


### Prerequisites

- Install Codex CLI or Claude Code on the computer that will run the investigation.
- Sign in to the correct Tellagen workspace.
- A local client is Codex or Claude running on your computer.
- An MCP server lets the local client call Tellagen or a provider tool.
- A provider tool gives the client read-only access to an evidence source, such as monitoring or infrastructure.
- Already configured? Start at [Check local setup](https://tellagen.com/help/run-local-diagnosis#step-check-local-setup).

## Procedure

<a id="phase-prepare-the-client"></a>

### Prepare the client

<a id="step-open-local-investigation-tools"></a>

1. **Open local investigation tools.** Open Settings. The navigation label is Local investigation tools. The page heading is AI diagnostics.

<a id="step-choose-a-client"></a>

2. **Choose a client.** Select Codex or Claude. Tellagen shows instructions for that client.

![Local investigation tools page with the three client setup steps.](https://tellagen.com/help/assets/local-diagnosis-setup.webp)

Choose a client before you copy its setup command.

<a id="step-create-the-api-key"></a>

3. **Create the API key.** Create a key with the Local Diagnosis preset. Store the token immediately because Tellagen shows it once.

![API key form with the Local Diagnosis preset and its scopes.](https://tellagen.com/help/assets/local-diagnosis-api-key-preset.webp)

The preset supplies the scopes needed by a local Diagnosis run.

<a id="step-copy-the-tellagen-command"></a>

4. **Copy the Tellagen command.** Find the Tellagen MCP card. Select Copy.

![Tellagen MCP setup card with its client install command and Copy action.](https://tellagen.com/help/assets/local-diagnosis-tool-command-2026-08-29.webp)

Copy the Tellagen MCP command for the selected local client.

<a id="step-add-required-provider-tools"></a>

5. **Add required provider tools.** Add only the provider MCP tools that the investigation needs. Keep their credentials in your local client.

<a id="step-check-local-setup"></a>

6. **Check local setup.** Select Check MCP tools. Paste the generated diagnostic prompt into your local client.

Codex configuration check:

```shell
codex mcp list
```

Claude configuration check:

```shell
claude mcp list
claude mcp get tellagen
```

<a id="step-review-the-setup-result"></a>

7. **Review the setup result.** Return to Tellagen. Make sure that required cards show INSTALLED and ACCESS OK. Review each stale result before use.

<a id="phase-run-the-investigation"></a>

### Run the investigation

<a id="step-open-diagnosis"></a>

8. **Open Diagnosis.** Open the incident. Select Diagnosis.

<a id="step-choose-the-run-relationship"></a>

9. **Choose the run relationship.** Select New independent run for a separate investigation. Select Follow up on this run to continue the selected result.

<a id="step-set-the-focus"></a>

10. **Set the focus.** Enter one focused question. Include the failed behavior, relevant service, and time window.

<a id="step-choose-evidence"></a>

11. **Choose evidence.** Open Evidence options. Enable Include incident Slack context only when the channel context is necessary.

<a id="step-start-the-handoff"></a>

12. **Start the handoff.** Select Run diagnosis. Copy the start command into your local client. Tellagen shows the run as waiting for local work.

<a id="phase-review-the-result"></a>

### Review the result

<a id="step-review-the-saved-result"></a>

13. **Review the saved result.** Review Investigation result, Evidence and checks, Run details, and Raw local tool trace. Separate observed evidence from suggestions.

## You are done when…

Tellagen stores the local run, checked evidence, findings, and trace on the incident.

## Troubleshooting

<a id="troubleshooting-the-page-says-no-diagnostic-tools-are-available-for-this-client"></a>

### The page says No diagnostic tools are available for this client.

Choose the client you installed, then copy and run the matching command from the MCP tool gallery.

<a id="troubleshooting-codex-shows-auth-unsupported-for-the-local-connection"></a>

### Codex shows Auth: Unsupported for the local connection.

This status is expected for this local connection. Tellagen authentication uses TELLAGEN_API_KEY in the local MCP configuration.

<a id="troubleshooting-run-diagnosis-is-not-available-after-setup"></a>

### Run diagnosis is not available after setup.

Confirm that the Local Diagnosis API key was created from the preset, that its owner has an active responder seat, and that the Tellagen MCP connection uses that key.

<a id="troubleshooting-diagnosis-ended-early-or-is-inconclusive"></a>

### Diagnosis ended early or is inconclusive.

Review Tool activity and the missing evidence in the Diagnosis tab. Fix the local tool or credential setup, then run a new diagnosis or a follow-up diagnosis.

<a id="troubleshooting-a-required-tool-does-not-show-installed"></a>

### A required tool does not show INSTALLED.

Run the install command for the selected client. Then run [Check MCP tools again](https://tellagen.com/help/run-local-diagnosis#step-check-local-setup).

<a id="troubleshooting-a-tool-shows-a-stale-result"></a>

### A tool shows a stale result.

Run the generated diagnostic prompt again. Use the result only after its status is current.

<a id="troubleshooting-the-local-client-cannot-call-tellagen"></a>

### The local client cannot call Tellagen.

The incident record and saved investigation results stay in Tellagen. Make sure that the key uses the Local Diagnosis preset and that the workspace URL is correct. Run [Check MCP tools again](https://tellagen.com/help/run-local-diagnosis#step-check-local-setup). If access still fails, ask a workspace settings administrator to review the key and local setup. Then email [Tellagen support](mailto:support@tellagen.com).

## Related articles

- **Recommended next task:** [Support Center](https://tellagen.com/help)
- [API reference](https://tellagen.com/api-reference)
- [Configure Codex for Diagnosis](https://tellagen.com/help/configure-codex-for-diagnosis)
- [Review Diagnosis findings](https://tellagen.com/help/review-diagnosis-findings)

## External setup references

- [OpenAI Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) (verified 2026-08-29)
- [Anthropic Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) (verified 2026-08-29)


## Continue through the incident lifecycle

- **Previous task:** [Track response actions and ownership](https://tellagen.com/help/manage-response-actions)
- **Next task:** [Review Diagnosis findings and evidence](https://tellagen.com/help/review-diagnosis-findings)
- [Back to Support Center](https://tellagen.com/help#help-search)

## Last verified date

2026-08-29