Skip to main content
gitnative

Docs / Agents

Give agents the same source-backed context as your team.

Connect the GitNative portable Agent Skill or hosted MCP server to search current workspace records and perform permitted actions without copying credentials into prompts.

Production MCP endpoint

Live
https://api.gitnative.dev/mcp
Open API keys Download setup files
Public plugin submissions are pending review
The OpenAI and Claude packages are prepared for review, but GitNative is not approved or listed in either public plugin directory yet. Local MCP and skill setup are available now.

Choose a client

Plugin and MCP setup

Public plugin installation and direct local MCP access use different authentication. Follow the section for the surface you are configuring.

ChatGPT and Codex plugin

The GitNative submission is prepared for the OpenAI plugin review process. It is not approved, published, or searchable in the public plugin directory yet.

Pending review
  1. 1After publication, open Plugins in ChatGPT Work, Codex, or the Codex CLI plugin browser.
  2. 2Search for GitNative, review the requested access, and install the plugin.
  3. 3Complete the browser sign-in flow when GitNative asks you to connect a workspace.
  4. 4Review or revoke the hosted connection from Settings → API Keys → Connected agents.
  5. 5Start a new task, then invoke GitNative directly or ask the agent to use workspace context.

GitNative implements the hosted OAuth connection used by ChatGPT. A local GitNative MCP key cannot configure ChatGPT and should never be pasted into a chat or plugin prompt.

Read the platform documentation

Codex local MCP

Connect Codex CLI, the IDE extension, or the desktop Codex environment directly with a workspace-scoped GitNative API key.

Available now
  1. 1Export GITNATIVE_MCP_KEY in the shell or secure environment that launches Codex.
  2. 2Add the server block to ~/.codex/config.toml for personal use or .codex/config.toml for a trusted repository.
  3. 3Restart Codex or start a new session, then confirm the gitnative server and tools are available.

Codex config.toml

[mcp_servers.gitnative]
url = "https://api.gitnative.dev/mcp"
bearer_token_env_var = "GITNATIVE_MCP_KEY"

Codex reads the environment of the process that launches it. It does not automatically load an arbitrary .env.local file.

Read the platform documentation

Claude Code

Use the hosted MCP endpoint today with a local key. The packaged Claude plugin is prepared for marketplace review but is not publicly listed yet.

MCP available now
  1. 1Export GITNATIVE_MCP_KEY before starting Claude Code.
  2. 2Add the server to a repository .mcp.json or your preferred Claude Code configuration scope.
  3. 3Restart Claude Code, approve the server if prompted, and verify that GitNative tools are connected.
  4. 4Add CLAUDE.md beside AGENTS.md so Claude imports the shared repository instructions.

Repository .mcp.json

{
  "mcpServers": {
    "gitnative": {
      "type": "http",
      "url": "https://api.gitnative.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${GITNATIVE_MCP_KEY}"
      }
    }
  }
}

The public Claude marketplace package is pending review. Local MCP setup and local plugin testing are separate from marketplace approval.

Read the platform documentation

Other MCP and Agent Skills clients

Use the canonical Agent Skill with any compatible client, and adapt the HTTP MCP configuration to that client’s documented format.

Available now
  1. 1Download the canonical GitNative SKILL.md into the skill directory supported by your agent.
  2. 2Configure an HTTP MCP server at the production endpoint with Authorization: Bearer followed by your key.
  3. 3Keep the key in the client secret store or launch environment, never in the skill or repository.
  4. 4Verify the connected workspace before using read or write tools.

Generic MCP JSON shape

{
  "mcpServers": {
    "gitnative": {
      "type": "http",
      "url": "https://api.gitnative.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${GITNATIVE_MCP_KEY}"
      }
    }
  }
}

Configuration filenames and environment-variable expansion differ by client. Follow your client’s documentation instead of assuming it loads this example unchanged.

Authentication

Use the right credential for the client

A GitNative developer key belongs to one developer in one active workspace. It is for local MCP clients; it is not an OpenAI credential and does not sign ChatGPT into GitNative.

Local Codex, Claude Code, and generic clients

  1. 1. Sign in to GitNative and select the workspace the agent should access.
  2. 2. Open Settings → API Keys, then reveal, rotate, or reissue your personal key.
  3. 3. Store it in the launch environment or secret store used by the client.
  4. 4. Rotate the key to replace it everywhere, or revoke it to stop access immediately.
export GITNATIVE_MCP_KEY="mcp_dev_live_replace_with_your_key"

Never commit the key, put it in AGENTS.md or SKILL.md, paste it into chat, or log the Authorization header.

Hosted ChatGPT

The ChatGPT plugin uses GitNative’s browser-based OAuth connection so the user can choose and authorize a workspace. Review or revoke the connection under Settings → API Keys → Connected agents. The OAuth flow is implemented, while public directory installation remains pending review. Static mcp_dev_live_... keys are not a supported end-user ChatGPT setup.

Repository setup

AGENTS.md and CLAUDE.md

Keep shared repository rules in one AGENTS.md file. Codex loads it directly. Claude Code loads CLAUDE.md, so the supplied bridge imports AGENTS.md instead of duplicating the rules.

For Codex and AGENTS.md clients

  1. 1. Download the AGENTS.md starter.
  2. 2. Merge it with existing repository instructions; do not overwrite project-specific commands.
  3. 3. Commit it at the repository root. Add narrower files only where a subtree needs different rules.

For Claude Code

  1. 1. Keep the same AGENTS.md at the repository root.
  2. 2. Add the supplied CLAUDE.md beside it.
  3. 3. Put Claude-specific additions below @AGENTS.md only when they cannot be shared.

Workspace control

The durable UI surface, available to agents

The capability catalog covers the same workspace records and actions as the authenticated product, subject to the connected user’s role and workspace scope. Browser-device interactions stay deliberately outside MCP.

Discover the right capability before acting

list_gitnative_capabilities searches by text, domain, or operation and returns cursor-based pages. The agent then uses read_gitnative for get, list, search, filter, and pagination, or mutate_gitnative for one authorized write, following the catalog's confirmation policy.

Each page includes bounded results and a continuation cursor. Agents should follow that cursor until it is empty when the request asks for every result.

Plan and deliver

Roadmaps, projects, tickets, bugs, releases, statuses, labels, dependencies, Git links, QA state, estimates, assignments, and archives.

Discuss and support

Comments, threaded replies, mentions, reactions, attachments, conversations, messages, clients, contacts, support requests, and client requests.

Meet and remember

Meeting records, participants, linked work, summaries, transcripts, action items, notes, decisions, knowledge search, and relationship graphs.

People and automation

Contributors, teams, invitations, roles, virtual developers, agent runs, integrations, migrations, pipelines, and repository sync.

Operate the workspace

Company and engineering settings, analytics, compliance, billing controls, GitHub, notifications, API keys, and scoped secret references.

Using the skill

Ask for an outcome, not a data dump

GitNative tools inherit the workspace and role attached to the credential. Read-only lookups are the safe default. Every write requires explicit intent; capabilities marked consequential also require a separate confirmation that names the target and proposed change.

“Find every open, high-priority ticket assigned to me. Follow pagination until there are no more results.”
“Find the decision history behind this service boundary and cite the relevant decision records.”
“Prepare a meeting brief from recent tickets, decisions, and prior meeting actions.”
“Log this progress note on GN-123. Do not change its status.”
“Archive Project Atlas after showing me the exact project and asking me to confirm.”

Control boundaries

Powerful where state is durable, constrained where it is not

Agent access mirrors workspace authorization; it does not bypass role checks, manufacture browser consent, or turn private credentials into searchable context.

Read freely, page completely

Read tools can search, filter, sort, and traverse cursor-based pages without changing workspace state.

Confirm consequential mutations

The live capability catalog marks destructive, external, billing, access, migration, and secret effects that require a separate confirmation of the workspace, exact target, and proposed change.

Keep secrets opaque

Discovery returns secret metadata and reference IDs, never stored values. Personal MCP keys and hosted OAuth connections are reviewed, rotated, or revoked only in the authenticated UI, never through agent tools.

Leave browser controls in the browser

Camera, microphone, screen share, WebRTC, drag gestures, clipboard, file pickers, theme state, and OAuth or payment consent are not agent tools. An agent can return a safe URL or operate on durable records around those flows.

Downloads

One skill, shared repository instructions

Download the portable GitNative skill with capability discovery, pagination, confirmation, and boundary guidance, then merge the instruction starters into your repository. Credentials stay outside every downloaded file.

GitNative skillThe canonical portable Agent Skill for searchable workspace context, paginated discovery, and confirmed mutations. Download AGENTS.md starterRepository guidance for Codex and other agents that support the AGENTS.md convention. Download CLAUDE.md bridgeA small Claude Code entry point that imports the shared AGENTS.md instructions. Download