Skip to main content
MCP (Model Context Protocol) is an open standard for connecting tools to models. Add a server such as Linear, Notion, or your own internal service to an agent config, and Omnara discovers its tools and makes them available to the model.

​
Declaring a server

Each entry under mcp: defines one server:

​
How MCP tools are named

MCP tool names combine the server and tool: mcp__{server}__{tool}. For example, Linear’s get_issue tool appears as mcp__linear__get_issue. These names appear in model_output tool calls and in GET /tool-calls with type: "mcp". Server names cannot contain underscores, and the combined name must fit within 64 characters.

​
Bearer auth

For servers that take a static token, store the token as a generic secret and reference it:
The examples assume the client, $ORG/orgID, and $PROJ/projectID setup from the quickstart.
The response’s id (sec_…) goes in auth.secret_id with type: bearer. Rotation is a new secret version — configs keep referencing the same ID.

​
AWS Signature Version 4 auth

For a SigV4-protected MCP server, create an AWS credentials secret in the dashboard, grant it to the project, and select AWS Signature V4 for server authentication:
Omnara optionally assumes the role stored with the credentials, then signs each request with AWS Signature Version 4 using the configured service and region. It does not modify the MCP request body or create a bearer token. auth.region is the MCP endpoint’s signing region; it does not limit the AWS resource regions selected in tool calls. Omnara does not refresh a session token stored in the AWS credentials secret, so rotate that secret before the token expires.

​
Connect with OAuth

For servers such as Linear, Omnara handles OAuth registration, authorization, and token exchange. It stores the resulting credentials in an oauth_token_set secret that your config references.
The CLI command runs the whole flow — it opens the server’s authorization page in your browser, waits for approval, and prints the created secret’s ID (--no-browser prints the authorization URL instead of opening it). The REST API and the SDK start the flow with one request and return an authorization URL to open yourself:
Open authorization_url in a browser and approve access. Omnara reads the server’s OAuth metadata, registers a client when supported, exchanges the authorization code, and stores the result as an oauth_token_set secret. You can also pass an existing client ID and secret (--client-id and --client-secret on the CLI, client_id and client_secret in the start request).The browser returns to the dashboard-relative return_to path with ?mcp_oauth=success&secret_id=sec_… appended. Absolute return URLs are rejected. Use that secret ID with auth.type: oauth. The authorization link is single-use and expires in 10 minutes.To authorize a server and attach it to an existing config in one step, use omnara agents mcp-add {agent-id} --server-name linear --mcp-url … or omnara profiles mcp-add {agent-profile-id} --server-name linear --mcp-url …. Both create the OAuth secret and add the mcp: entry to the agent’s or profile’s config for you.
Re-running the flow with the same owner and name creates a new version of the same secret, so re-authorizing never forces a config change. Troubleshooting:
  • If the MCP server doesn’t actually require auth, the start call returns 409 — declare it without an auth block instead.
  • If a token expires and cannot be refreshed, affected tool calls return mcp_connection_failed. Re-run the OAuth flow to create a fresh secret version; the config can keep using the same secret ID.
Full schema and playground: Start MCP OAuth for a new secret.