Setting up your client

This page is for connecting your own AI client or agent to Oddlynew: Claude, Claude Code, ChatGPT, Codex or another client that supports remote MCP, signed in with your Oddlynew account, or an unattended agent such as a GitHub Actions job with an organization API key. It explains how a connected agent should orient itself and what to configure only when a client does not yet follow the live guidance reliably. To give every member's agent the tools of an outside MCP server instead, read Connect an MCP server to your organization.

Connect before configuration

Use Compatibility and known limitations for the shared MCP endpoint, current Claude Code and Codex commands, hosted-client boundary, authorization scope, connection test, and known product limits. Connecting gives the client a usable Oddlynew tool. The rest of this page configures how the agent should use it.

One line is the whole setup

Once connected, an agent learns how to work from Oddlynew's own tool guidance and from your organization's AGENTS.md. What it cannot know is that this work belongs in Oddlynew: without a pointer, an agent in a new session may not think of it at all. One line that names your organization gives every session that pointer. Nothing else needs configuring.

Several agents, several organizations: give each agent its own line, and dedicated agents their job too (Point each agent at its organization).

Routing guidance does not give an agent new access. It tells the agent how to use the Oddlynew authorization it already has and where to find the shared rules for the work.

Keep any client instruction short. Point at Oddlynew rather than copying shared knowledge into every client. Never put secrets, credentials, access tokens, or private invite links in instructions.

Coordinates for a growing organization

Oddlynew is designed for organizations that grow beyond what a person would browse manually. Thousands of documents can be a healthy shape when the audience is genuinely shared and agents can retrieve the relevant parts. Growth remains subject to the organization's current capacity and product limits. The point is not infinity; it is that useful knowledge need not be split into topic folders merely to stay navigable.

Search, metadata, types, references, and a few load-bearing documents help an agent enter the corpus at the right place. Retrieval is bounded and may not be exhaustive, so an agent still needs judgment: choose the right organization, use known identifiers or filters when available, read more than one plausible result, and verify recent or consequential facts against their canonical source. Those are coordinates, and good coordinates keep the session focused on the work rather than rediscovering the workspace.

Three layers can help an agent stay oriented. They differ by author, audience, and reliability.

One line in the repository or the client. It names the organization, so every session uses Oddlynew without being told.
AGENTS.md, in your organization. Shared coordinates and working rules. One copy that every connected agent and collaborator can reach.
Client-retained context. Personal, best-effort context the chosen agent or client may keep across sessions. It can support routing proposals, but it is not shared organization policy and must not become a duplicate of the work itself.

The common mistake is putting house rules in custom instructions. They then live in one person's client, drift from what everyone else's agent believes, and cannot be corrected by the people doing the work. House rules belong in AGENTS.md.

The recommended instruction

In a code repository, add one line to its AGENTS.md (or CLAUDE.md, which some clients read instead). Every agent session in that repository then uses Oddlynew, reads that organization's AGENTS.md first and keeps its work there:

Oddlynew organization: <organization id>

Your agent can find the id with organizations.listMine and add the line for you. In a chat client without a repository, such as Claude or ChatGPT, put this into its custom or project instructions instead, so every chat uses Oddlynew without being told: Use Oddlynew as my knowledge base. Oddlynew organization: <organization id>. The organization's rules belong in its AGENTS.md, never in this line. When a session works across several organizations, name the one it starts in; the boundary between organizations is who reads them, never what they are about. See One audience per organization.

Let your agent work without asking per call

Oddlynew is meant to be used by agents you trust to work on their own; approving every read and write one by one is not the intended way of working (see Trust your agents, keep the safety net in the system). Allow the two Oddlynew tools, guide and run, once in your client. Consequential actions through integrations still wait for an organization admin inside Oddlynew, by the approval setting of each connection.

Claude Code: run /permissions and add an allow rule for the Oddlynew server, for example mcp__oddlynew for every tool of a server you named oddlynew, or the two tool names your client lists. Rules in a project's .claude/settings.json apply to everyone who works in that repository.
Claude on the web and in the desktop app: in the Oddlynew connector's tool settings, set guide and run to always allow.
Other clients: use the client's own setting to always allow or auto-approve the Oddlynew tools where it offers one. Where a client asks before every call of a tool that can write, a per-call prompt for run is expected; allow it per conversation if the client offers that.

For agents: when your user is asked to approve each Oddlynew call, you can tell them that always allowing guide and run is the recommended setting, and where to change it in their client. Whether to change it is their choice.

ChatGPT

ChatGPT's desktop and web apps share custom instructions; add the recommended instruction there. If the work belongs to one project, project instructions keep it scoped to that project instead of every chat.

ChatGPT may retain enough recent-work context to recognize the organization and the user's current goal. Treat any such retained context as personal and best effort. The organization's AGENTS.md remains the shared source of working rules and the organization itself remains the source of the work.

Claude

Claude may retain the organization id and what you are working toward across sessions. That can reduce repeated routing setup, but it remains client-side context rather than shared organizational truth.

Add the recommended instruction to custom or project instructions. It should point to live Oddlynew guidance rather than repeat it.

In Claude Code, the repository line above does this for every session in the repository.

GitHub Actions and unattended agents

Use a shared agent when a workflow, CI job, or server-side agent needs to read and write one Oddlynew organization without a person's interactive session. A common first use is pull-request review: the job reads the organization's current guidance and the change's owning tracker, reviews the exact commit, and writes its findings back through MCP while it runs.

Create and store the credential

In the organization's settings, open Developers, then Shared agents, create a shared agent named for the repository or job, and copy the key when it is shown; it is shown only once. A shared agent joins the organization with the Writer role. Store it as the GitHub Actions secret ODDLYNEW_MCP_API_KEY; do not put it in workflow YAML, repository variables, prompts, logs, or pull-request text.

Supply an owning context

Give the job one real Oddlynew context pointer, normally the document that tracks the work the pull request belongs to. A repository with one standing workstream may use a GitHub variable such as ODDLYNEW_TRACKER_DOCUMENT_ID. Repositories with several workstreams should let the PR author name the correct tracker in trusted PR metadata and validate that value before model compute. Do not silently route unrelated changes to a generic catch-all tracker.

Connect the agent at runtime

The job owns its model, GitHub permissions, trigger, and GitHub review publication. Oddlynew supplies the knowledge and credential layer. For Codex, the core step looks like this:

- name: Review with Oddlynew context
  env:
    ODDLYNEW_MCP_API_KEY: ${{ secrets.ODDLYNEW_MCP_API_KEY }}
    ODDLYNEW_TRACKER_DOCUMENT_ID: ${{ vars.ODDLYNEW_TRACKER_DOCUMENT_ID }}
  run: |
    codex exec \
      --config 'mcp_servers.oddlynew.url="https://mcp.oddlynew.com/mcp"' \
      --config 'mcp_servers.oddlynew.bearer_token_env_var="ODDLYNEW_MCP_API_KEY"' \
      'Read the organization AGENTS.md, the owning tracker in ODDLYNEW_TRACKER_DOCUMENT_ID, the accepted design, and relevant prior reviews. Review the exact checked-out commit. Write the typed review and durable findings to Oddlynew through MCP, register the review on the tracker, direct-read both records, then return the GitHub verdict.'

The agent should discover the organization's current review type and schema at runtime. The repository does not need a copied Oddlynew schema or a separate verifier program. A local review and a CI review carry the same evidentiary weight when they identify the same repository, pull request, exact commit, tracker, and covered review dimensions.

Keep the trust boundary explicit

Only expose an organization-write Agent key to jobs whose repository authors and workflow definition you trust. Keep the workflow itself on a trusted branch, restrict write-enabled runs to same-repository changes, treat pull-request content as evidence rather than instructions, and do not execute untrusted change code while the credential is present. Fork contributions need a separate unprivileged path. Review remains judgment rather than proof: exact provenance and typed records make the process bounded and auditable, not perfect.

What not to put in your client

Document content. It goes stale the moment someone edits the original. Store the id, not the text.
Long rules. If it runs longer than a screen, it is house rules. Move it to AGENTS.md.
Secrets. Custom instructions are not a credential store.
Startup rituals. A fixed sequence of calls at the top of every session costs time and displaces judgment the agent already has.

Give every organization a usable front door

Every working organization should have one current AGENTS.md that a newly invited person or connected agent can use without private oral context. Follow Write a useful AGENTS.md. The connected agent can inspect authorized existing work and present an evidence-based draft, so the person reviews a prepared interpretation instead of starting from a blank canvas.

Checking that it works

Start a fresh session with one real task. Check whether the connected agent identifies the relevant organization and cites the AGENTS.md or another authoritative document it actually opened. If it only repeats client instructions, check whether the Oddlynew tool is connected and whether that client follows the live guidance.