Odysseus AI MCP Setup: Servers, OAuth, and Troubleshooting

What MCP means inside an Odysseus workspace

Model Context Protocol (MCP) lets an AI application discover and call tools exposed by a server. A server can provide read-only documents, calendar lookup, search, or an action such as creating a task. The server defines the tool schema; the host decides when to connect, which tools to show, and whether a person must approve a call.

Do not treat the model, the workspace, and the MCP process as one trust zone. A local model may still send a query through a remote tool provider. Identify the host, registered server, exposed tools, and destination of each result before adding credentials or private files.

Before setup: authentication, admin access, and network boundaries

Odysseus documents MCP management and API-token administration in the admin area. Use an authorized account and confirm that the server process loaded the same environment settings as the web interface. A working browser session does not prove that the runtime can reach an MCP endpoint.

Keep authentication enabled while testing. For Docker deployments, OAuth callbacks and service names must resolve from the container network. Prepare one server, one read-only tool, a non-sensitive workspace, and an expected result so the change can be removed without guessing what else it affected.

Review built-in MCP servers and the npx cache

A built-in entry is a registration shortcut, not a health guarantee. The command must exist in the same image or container, start with the intended arguments, and reach its runtime dependencies. Some examples resolve an npx package from a local cache, so review the approved package and version before relying on it.

Start with discovery. Read startup output and confirm that Odysseus can list tool names and schemas without executing a tool. On an isolated host, use an approved cache or a local command instead of retrying a registry lookup that cannot succeed.

1. Choose a low-risk entry

   Use a test resource or read-only list; avoid shell and broad file access.

2. Check the runtime

   Run the command from the Odysseus image and redact stderr.

3. List tools first

   Review names, schemas, and capabilities before approving a call.

npx -y @playwright/mcp@latest --help

docker compose logs --tail=120 odysseus

Add a remote MCP server with OAuth

Remote OAuth adds an identity exchange to the transport and tool handshake. Odysseus starts authorization, the user grants scopes, and the provider redirects the browser to the registered callback. A localhost callback inside a container cannot serve an external browser.

The Odysseus setup guide documents OAUTH_REDIRECT_BASE_URL for remote MCP servers. Set it at the deployment boundary, keep the scheme and path stable, and restart the service that reads the environment. A successful callback proves identity only; list tools, review the token scope, and run one harmless read before enabling writes.

1. Confirm the callback

   Record the provider's exact HTTPS path and scopes.

2. Set OAUTH_REDIRECT_BASE_URL

   Add it to the deployment environment and restart the owning process.

3. Limit the first call

   Choose a read-only tool and compare the response with its schema.

OAUTH_REDIRECT_BASE_URL=https://mcp.example.com/oauth/callback

Use a repeatable test path for health and tools

Run the same sequence for every Odysseus AI MCP change: check workspace health, check the server process, list tools and schemas, then make one call with a known input. This separates inference, transport, permission, and provider failures instead of reporting one generic connection error.

Record the server and tool name, argument shape, status, duration, and a safe request identifier. Remove tokens, authorization headers, private documents, and complete prompts. Use a fixture, test calendar, or harmless endpoint so the test is reversible.

1. Check workspace health

   Fix Odysseus startup or dependency errors first.

2. List schemas

   Confirm names, required arguments, and read or write capabilities.

3. Run one bounded read

   Compare the result with the documented schema and record only safe evidence.

Fix unreachable servers, permissions, and stale registrations

Start at the failed layer. A process that exits points to its command, package, directory, or environment. A running process with no tools points to transport or handshake. A visible tool that fails points to arguments, OAuth scope, quota, or its upstream endpoint. A model that ignores a working tool may also have a host or tool-calling problem.

Container networking causes many false failures. Test the endpoint from the Odysseus runtime, check certificates and outbound policy, and use the correct service name or host gateway. After changing a command, callback, or variable, restart the owner process and remove duplicate registrations. Revoke old grants and rotate a credential if it appeared in logs or terminal history.

Apply a practical token and network checklist

The safest MCP configuration is the smallest one that solves the task. Allow only needed folders, domains, and actions; prefer read-only tools; require visible approval for writes; and plan credential rotation. A local process can still forward prompts, search terms, or file excerpts to an external provider.

Keep authentication and HTTPS, restrict admin access, and keep raw model and service ports private. Store secrets in the environment or a secret manager, mask them in logs, and document who owns each server and how to revoke it. Test the revoke path before the integration becomes urgent.

• Use a test account or workspace for the first connection.
• Review commands and package versions.
• Grant the smallest directory, domain, and tool scope.
• Mask tokens, private documents, and complete prompts in logs.
• Document deletion and rotation after accidental exposure.