Tools and integrations

A coding agent can work on a laptop, in a hosted VM, or in CI. Those environments rarely have the same tools or connectors. Every covered repository provides a portable baseline for routine work and declares anything outside it.

Provide a portable baseline

Reading, editing, building, and testing the repository must work without an external connector. The checked-in development environment provides these capabilities:

Language servers are useful but not portable across the approved agents. A repository may provide one as an optional integration. The development environment installs and pins it. The agent must not download one during a session.

Provider-specific features may extend this baseline. They cannot replace it.

Declare tools in AGENTS.md

Put a capabilities table and an integrations table under Setup in the root AGENTS.md. Keep the entries short and link longer setup instructions.

## Setup

### Capabilities

| Capability | Command | Check |
| --- | --- | --- |
| Repository tasks | `pnpm` scripts | `pnpm agent:check` |
| Search | `rg`, `fd`, `jq` | `pnpm agent:check` |
| TypeScript diagnostics | `pnpm typecheck` | `pnpm agent:check` |

### Integrations

| Integration | Status | Agents and environments | Authentication | Fallback or stop | Owner |
| --- | --- | --- | --- | --- | --- |
| GitHub | Required for pull request work | All agents; local, cloud, CI | Payward SSO or job identity | `git` for local history; stop for pull request state | `@org/team` |
| Storybook MCP | Optional | All agents; local | None | Read stories and source files | `@org/team` |

Use these status values:

• Baseline for a capability available to every approved agent.
• Required for a named task when that task cannot proceed without the integration.
• Optional when the integration only saves time or improves discovery.

An unavailable required integration has either a portable fallback or a stop condition. Never substitute guesses, web search, or stale documentation for missing access.

Keep one MCP source

Use the repository-root .mcp.json as the canonical MCP source. Claude Code reads it directly. A tested adapter emits or checks the equivalent native configuration for the other approved agents:

• Codex uses .codex/config.toml.
• Cursor uses .cursor/mcp.json.
• OpenCode uses the mcp section of opencode.json.

The formats are not interchangeable. Do not call .mcp.json a portable provider file. CI fails when a native entry drifts from the canonical source.

This example connects every local agent to the same Storybook server:

{
  "mcpServers": {
    "storybook": {
      "type": "http",
      "url": "http://127.0.0.1:6006/mcp"
    }
  }
}

[mcp_servers.storybook]
url = "http://127.0.0.1:6006/mcp"

{
  "mcpServers": {
    "storybook": {
      "type": "http",
      "url": "http://127.0.0.1:6006/mcp"
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "storybook": {
      "type": "remote",
      "url": "http://127.0.0.1:6006/mcp",
      "enabled": true
    }
  }
}

Distribute organization-wide connectors through managed provider configuration. Commit repository configuration for repository-specific connectors. If a repository depends on an organization-managed connector, declare it in AGENTS.md without copying its managed configuration.

Keep credentials outside the repository

Payward provides enterprise accounts for Claude, Cursor, and OpenAI through ConductorOne and Okta. Company repository work uses those accounts, never a personal provider account. OpenCode connects through an approved Payward model-provider identity or gateway.

Do not commit:

• Credentials or resolved secrets.
• Private keys.
• Literal authorization headers.

MCP configuration refers to environment variable names. It does not contain their values.

Prefer 1Password Environments for project variables shared by a team. They can mount a local .env file without writing plaintext secrets to disk. Use SecretSpec or op run when the command needs process-scoped injection instead.

An approved local client that supports stdio may use the 1Password MCP server to manage Environments and local mounts. The server exposes variable names, but it does not return stored values to the client. Remote-only agents cannot use this local server.

A committed .envrc may activate the development environment and check required variable names with env_vars_required. It is not a credential store.

eval "$(devenv direnvrc)"
use devenv

env_vars_required MCP_ACCESS_TOKEN

Keep local values in an ignored file when process-scoped loading is unavailable. Use dotenv_if_exists for dotenv data. Do not load an unchecked nested .envrc, and do not copy a dotenv secret file into the Nix store.

Run each agent as a child of the credential loader:

secretspec run -- claude

secretspec run -- codex

secretspec run -- cursor-agent

secretspec run -- opencode

Unattended work uses an organization-owned service identity. Prefer workload identity or OIDC. Use an approved secret manager only when federation is unavailable. Never copy a person’s token into CI.

Account for every execution environment

Declare where each integration works. Local configuration does not automatically carry into a hosted agent or CI job.

Remote-control sessions use the machine that runs their tools. Treat them as local execution unless the provider runs a named tool remotely.

Approve and own integrations

Before using a connector, check Payward’s Approved Tools and MCP Guidance and Approved and Prohibited Software for Company-Issued Computers.

• A repository-local connector that processes only local development data needs owning-team review.
• An external connector or one that accesses company systems needs organization approval before the repository depends on it.
• A closed-source connector follows the Security GRC review linked from Payward’s MCP guidance.
• An open-source MCP server follows Payward’s open-source software approval process.
• An internally hosted MCP server:
  • Forwards the caller identity instead of hiding callers behind one MCP service account.
  • Logs requests.
  • Has an SCID.
  • Stays patched.
  • Lives in a team repository.
  • Runs shift-left security checks.
  • Receives AppSec review.

Add explicit CODEOWNERS entries for executable agent configuration and its scripts. Cover every path that exists in the repository:

/.mcp.json       @org/team
/opencode.json   @org/team
/.claude/**      @org/team
/.codex/**       @org/team
/.cursor/**      @org/team
/.opencode/**    @org/team
/scripts/agent/** @org/team

Treat hooks, plugins, custom tools, and local MCP launchers as code:

• Pin executable packages and dependencies.
• Install them through the checked-in development environment.
• Review changes through the declared owner.
• Test behavior with sanitized fixtures.

Personal integrations remain user-scoped. They must already be approved for company data, cannot weaken managed controls, and cannot become necessary to complete or review a change. When a team starts relying on one, declare it.

Test tools before relying on them

Expose two logical tasks through the repository’s canonical command interface:

• agent-check verifies required binaries, supported versions, configuration syntax, and referenced files without using the network.
• integration-check <name> verifies authentication and connectivity for one declared integration. Missing access reports BLOCKED with the setup or stop condition.

The exact command follows the repository’s existing interface, such as just agent-check, pnpm agent:check, or sbt agentCheck.

This agent-check example checks the portable command baseline and validates each native MCP file that exists. The checked-in development environment installs taplo when the repository has Codex TOML configuration.

#!/usr/bin/env bash
set -euo pipefail

IFS=' ' read -r -a required_tools <<<"${AGENT_CHECK_TOOLS:-git gh rg fd jq}"

for tool in "${required_tools[@]}"; do
  if ! command -v "$tool" >/dev/null 2>&1; then
    printf 'BLOCKED tool:%s: not found on PATH\n' "$tool" >&2
    exit 1
  fi
done

for config in .mcp.json .cursor/mcp.json opencode.json; do
  if [[ -f "$config" ]] && ! jq empty "$config"; then
    printf 'FAIL config:%s: invalid JSON\n' "$config" >&2
    exit 1
  fi
done

if [[ -f .codex/config.toml ]]; then
  if ! command -v taplo >/dev/null 2>&1; then
    printf 'BLOCKED config:.codex/config.toml: taplo is not installed\n' >&2
    exit 1
  fi
  if ! taplo check .codex/config.toml; then
    printf 'FAIL config:.codex/config.toml: invalid TOML\n' >&2
    exit 1
  fi
fi

printf 'PASS agent-check\n'

@test "agent-check reports a missing tool as blocked" {
  cd "$TEST_REPO"
  AGENT_CHECK_TOOLS="missing-agent-check-tool" run scripts/agent-check

  [ "$status" -eq 1 ]
  [[ "$output" == *"BLOCKED tool:missing-agent-check-tool"* ]]
}

@test "agent-check rejects invalid MCP JSON" {
  cd "$TEST_REPO"
  printf '{' >.mcp.json

  AGENT_CHECK_TOOLS="jq" run scripts/agent-check

  [ "$status" -eq 1 ]
  [[ "$output" == *"FAIL config:.mcp.json: invalid JSON"* ]]
}

An integration check names one declared dependency and makes the smallest read-only request that proves both authentication and connectivity. It never falls through to an undeclared target.

#!/usr/bin/env bash
set -euo pipefail

integration="${1:-}"

case "$integration" in
  github)
    check=("${GH_BIN:-gh}" api user --silent)
    ;;
  storybook)
    check=(
      "${CURL_BIN:-curl}"
      --fail
      --silent
      --show-error
      "${STORYBOOK_URL:-http://127.0.0.1:6006/}"
    )
    ;;
  *)
    printf 'Usage: %s <github|storybook>\n' "$0" >&2
    exit 64
    ;;
esac

if ! "${check[@]}" >/dev/null; then
  printf 'BLOCKED integration:%s: authentication or connectivity failed\n' "$integration" >&2
  exit 1
fi

printf 'PASS integration:%s\n' "$integration"

@test "integration-check probes GitHub with the current identity" {
  GH_BIN="$PROBE" run scripts/integration-check github

  [ "$status" -eq 0 ]
  [ "$output" = "PASS integration:github" ]
}

@test "integration-check reports a failed probe as blocked" {
  export PROBE_STATUS=7

  CURL_BIN="$PROBE" run scripts/integration-check storybook

  [ "$status" -eq 1 ]
  [[ "$output" == *"BLOCKED integration:storybook"* ]]
}

The examples/tools-and-integrations folder contains the executable commands and their full Bats suites. Each suite compares the published command with the tested file.

Every pull request that changes agent configuration checks:

• Configuration syntax or schema.
• Referenced commands and files.
• Hook and adapter behavior against sanitized events.
• Provider discovery through a noninteractive validation command when the provider supplies one.
• Committed files for literal credentials and authorization headers.

Do not call a production connector merely to validate configuration. Required external integrations instead run a scheduled, read-only connectivity check from a managed non-production identity. The owning team receives failures.

Optional integrations may improve discovery and speed. They do not change:

• Required checks.
• Acceptance criteria.
• Generated artifacts.
• Review evidence.
• Stop conditions.

References

• Claude Code settings and MCP, project configuration and connector discovery.
• Codex configuration and MCP, trusted project settings and native MCP tables.
• Cursor MCP and Cloud Agent setup, local and hosted configuration.
• OpenCode configuration and MCP servers, stable project configuration and environment references.
• devenv and SecretSpec, process-scoped secret loading from declared providers.
• 1Password CLI environment variables, resolving secret references for one child process.
• 1Password Environments and MCP server, shared project variables, local mounts, and agent-assisted environment management.
• direnv standard library, required-variable checks and guarded dotenv loading.
• Taplo validation, syntax and schema checks for Codex TOML configuration.
• Development environment, installation and version pinning for repository tools.
• Task automation, the canonical command interface and tests for its public tasks.
• Agent instructions, approved agents and repository instruction discovery.
• Security and data, permissions, secrets, external content, and data handling.
• Audit responsibilities, retention and evidence requirements.