Codex Setup

Use this guide when Codex should use Roster tools for customer approval routing, participant lookup, delegations, labels, projects, and Resolve history.

Prerequisites

• A reachable Roster MCP endpoint, such as https://roster.example.com/mcp.
• ROSTER_MCP_RESOURCE_URI set to the exact public MCP URL.
• ROSTER_MCP_AUTH_MODE=oauth for normal end-user access.
• Optional: ROSTER_MCP_AUTH_MODE=api_key for API-key-only deployments, or api_key,oauth when OAuth and API-key clients are both allowed.

For example:

ROSTER_MCP_RESOURCE_URI=https://roster.example.com/mcp

Add The Server

Roster is a Streamable HTTP MCP server. Add it with the Codex CLI:

codex mcp add roster --url https://roster.example.com/mcp
codex mcp list

You can also add it from the Codex UI. Open Settings > Integrations > MCP servers, select Add server, choose to connect a custom MCP server, select Streamable HTTP, then enter:

Name: roster
URL: https://roster.example.com/mcp

For OAuth, leave Bearer token env var empty. For API-key mode, see API-key setup for Codex.

After saving, roster appears in the MCP servers list. Keep the server toggle enabled before starting a Roster-backed Codex task.

You can also edit ~/.codex/config.toml directly:

[mcp_servers.roster]
url = "https://roster.example.com/mcp"

For OAuth, run this if the browser login does not start automatically, or after editing config.toml directly:

codex mcp login roster

Codex stores the OAuth grant locally after login. Restart Codex after changing the configuration, then use /mcp to confirm that the roster server is connected.

API-Key Setup For Codex

Use API keys only for automation flows that should not open an OAuth browser flow. The key is a Roster API key for the acting identity; it is not the Roster server’s deployment secret. To obtain and use one:

1. In Roster, an admin opens Identity and Access > API Keys.
2. Create a key for the active identity that should own the Codex actions.
3. Grant only the needed MCP scopes.
4. Copy the one-time rst_... token and store it in a secure environment variable, for example:

export ROSTER_MCP_BEARER_TOKEN="rst_..."

5. In the Codex UI, set Bearer token env var to that variable name:

Bearer token env var: ROSTER_MCP_BEARER_TOKEN

Or configure the same value in ~/.codex/config.toml:

[mcp_servers.roster]
url = "https://roster.example.com/mcp"
bearer_token_env_var = "ROSTER_MCP_BEARER_TOKEN"

Codex sends the key as a bearer token to the MCP endpoint:

Authorization: Bearer rst_...

Use a narrow key for resolve-only workflows:

mcp:resolve mcp:resolve-requests:read mcp:projects:read mcp:participants:read

Use broader write scopes only when Codex is expected to create or update Roster data. API-key access is still limited by the key owner’s Roster permissions and the target resource rules.

Tool Selection

Adding the MCP server gives Codex access to Roster tools, but it does not guarantee Codex will choose Roster for every relevant prompt. A customer workspace can distribute a Roster instruction or skill so Codex knows Roster is the source of truth for approval routing, ownership, participants, delegations, projects, labels, and recent Resolve history.

Codex Skill

Use this skill instruction when packaging Roster behavior for a customer workspace:

---
name: roster
description: Use live Roster MCP for approval routing, ownership, participants, delegated contacts, project membership, labels, and latest Resolve request retrieval. Use when the user asks who should approve, handle, review, own, or be contacted for a business task, even if the user does not mention Roster by name.
---

# Roster

Use the live Roster MCP server as the source of truth for current operational
answers. Do not reconstruct Roster data from files or stale examples when
MCP is available.

## Workflow

1. For open-ended routing or contact questions, call the Roster `resolve` tool.
2. For latest Resolve history, call `list_resolve_requests`, choose the newest
   request, then call `get_resolve_request`.
3. For exact project, participant, label, delegation, or membership checks, use
   the matching Roster lookup tools.
4. Return only the fields or contacts the user asked for.

Skill Distribution

For customer or team distribution, package the skill as a Codex plugin. Keep the customer’s Roster MCP URL and authentication in their Codex MCP settings because those values are deployment-specific.

A small Roster plugin can be as simple as:

roster-codex-plugin/
  .codex-plugin/
    plugin.json
  skills/
    roster/
      SKILL.md

Example plugin.json:

{
  "name": "roster",
  "version": "1.0.0",
  "description": "Roster approval-routing workflows for Codex.",
  "skills": "./skills/"
}

Customer rollout:

1. Publish the customer-hosted Roster MCP endpoint with OAuth enabled.
2. Ask users to add the MCP server and complete OAuth login.
3. Distribute the Roster Codex skill or plugin.

Connection Check

Ask Codex:

Use Roster to list my visible projects, then resolve who should handle vendor
security review for Atlas Operations.

Then test implicit routing without naming Roster:

Who should approve vendor security review for Atlas?

Codex should choose the Roster workflow and return the selected participants or contacts. If it does not, tighten the distributed instruction or skill description, then restart Codex if the updated skill is not detected.

If the server connects but tools return insufficient_scope, update the Roster API key or OAuth grant to include the missing mcp:* scope.