Why does the agent say the omeka server needs authentication?
The agent has not signed in yet, or its sign-in expired. In Claude Code, type /mcp, choose omeka and Authenticate, or run claude mcp login omeka. In Codex, run codex mcp login omeka. If you use an API key, check that the Authorization header or OMEKA_MCP_TOKEN variable holds KEY_IDENTITY:KEY_CREDENTIAL with a colon between them.
Why does the sign-in page say "Cannot connect this app"?
The app sent a request this site cannot accept, usually because it was registered with a different return address or its registration was removed. Remove the server from the agent, add it again, and sign in again. If it keeps happening, an administrator should check that Let apps connect by signing in is turned on in the module settings.
How do I sign in on a machine without a browser?
In Claude Code, run claude mcp login omeka --no-browser. It prints the sign-in address; open it on any device, approve, and paste back the address your browser ends up on. Alternatively, use an API key.
Why can't the agent create or edit anything?
The editing tools are only offered when all of these are true:
- You ticked Create and edit when you approved the agent. Disconnect it on Admin > MCP connections and sign in again to change this.
- Your Omeka role can create items. Researchers can only read.
- The site is not in read-only mode, and an administrator has not disabled the tool in the module settings.
Why do requests with an API key fail with "not accepted"?
Check that the key still exists on your user page and that your account is active. If the key is right, the web server may be removing the Authorization header before it reaches Omeka; some Apache setups with PHP-FPM do this. An administrator can test this with Run check in the module settings and fix it by adding CGIPassAuth On to the Apache configuration.
Why does an upload fail?
The upload response says why:
- 404 or 410: the upload address expired or has been used for all its files. Ask the agent to request a new one.
- 400, too large: the file is bigger than the server accepts. The limit comes from PHP's
upload_max_filesizeandpost_max_sizesettings. - 422: the file type is not allowed. Administrators manage allowed media types and extensions under Admin > Settings > Security.
Why does adding media from a web address time out?
The server downloads the file while the tool runs, and agents stop waiting after a while: Codex after 60 seconds unless tool_timeout_sec is raised. Raise the timeout, or download the file and upload it from your computer instead.
Why are results cut off?
Claude Code limits each tool result to 25,000 tokens. Ask the agent for smaller pages of search results, or start Claude Code with MAX_MCP_OUTPUT_TOKENS=50000 claude.
Why are requests refused with 429 or 403?
If the Traffic Guard module is installed, it rate-limits MCP requests in its own MCP category. An administrator can raise that limit in Traffic Guard's settings, or add the agent's IP address to its allowlist.
How do I see what the agent changed?
The agent reports the records it created or edited, with links. New records are private by default and may be gathered in an intake item set. With the Audit Trail and Resource Versioning modules installed, every change is logged under your name and can be rolled back.
How do I disconnect an agent?
Choose Disconnect next to it on Admin > MCP connections; its access stops immediately. For API keys, delete the key on your user page.