# MCP or CLI is not working

> Diagnose agent connection, CLI authentication, project selection, and safe-write failures.

Canonical page: https://anectico.com/docs/help/agents-and-cli/


Start outside the AI client so authentication and project failures are visible directly:

```bash
anectico whoami
anectico projects list
anectico doctor
```

For API-key use, confirm `ANECTICO_API_KEY` is available to the process that launches the CLI or MCP
client—not only to your interactive shell.

## The MCP client cannot connect

Confirm the remote URL and bearer key match [Connect an MCP client](/docs/agents/connect-mcp). Restart
the client after changing its configuration. A key needs `mcp:read`; write tools also need
`mcp:write` and their domain scopes.

If the connection succeeds but no tools appear, inspect the client's MCP logs for an authentication
response and verify it supports remote HTTP MCP. Do not paste the key into chat.

## Documentation tools are missing or unauthorized

Documentation reads need both `mcp:read` and `docs:read`. All organization roles include
`docs:read`, but a minted API key carries only its explicit scopes. The `investigate` and `incident`
bundles include it; custom keys and the `agent-observability` or `admin` bundles may not. Mint a
replacement with `--scope docs:read` if needed, then reconnect with that key.

Also inspect the MCP URL: `?profile=agent-observability` excludes documentation regardless of key
scopes. Remove that filter or choose a docs-capable profile. A `search` source marked
`unauthorized` means a missing scope; `out_of_profile` means the connection filter excluded it.

`search_docs` and `get_doc` are read actions, not standalone entries in the tool list. Discover
them with `list_read_actions`, then invoke `execute_read_action`. Pass a search hit's `slug` to
`get_doc`, or its `ref` to `fetch`; the two identifiers are not interchangeable. Public
[Markdown documentation](/docs/reference/machine-readable-docs) needs no credential.

## A CLI command returns the wrong project or no rows

```bash
anectico projects use my-app
anectico persons search test-user
```

Check environment and time filters next. Piped CLI output is JSON; interactive output is formatted,
so a parser should consume the piped form rather than scraping terminal tables.

## A write is missing or refused

Destructive CLI commands require `--yes`. MCP clients may also require an interactive confirmation.
If a tool is absent, the server may have hidden it because the key lacks `mcp:write` or the relevant
domain permission. Regenerate a purpose-specific key instead of broadening a shared key.

Use `anectico docs --markdown` to confirm the installed CLI's exact command and flag surface. Upgrade or
pin the CLI if an automation was written for a different early-access version.

- [Use the Anectico CLI](/docs/agents/cli)
- [Permissions and safe actions](/docs/agents/permissions-and-safety)