Requirements

Node.js 20 or newer
pnpm
Docker with Compose

Install

pnpm install
cp .env.example .env.local

Generate separate secrets for the Auth.js session and the signed web-to-API boundary:

openssl rand -base64 32

Set DATABASE_URL, AUTH_URL, AUTH_SECRET, and WEB_INTERNAL_SECRET in .env.local. Set DEV_AUTH_BYPASS=true only for local development.

Start

docker compose up -d postgres
pnpm db:migrate
pnpm db:seed
pnpm dev

The web dashboard runs at http://localhost:3000; REST and MCP run at http://localhost:3001. The local seed provides Alice and Bob in Acme plus Mallory in a separate organisation.

pnpm dev loads the root .env.local for both services. When deliberately using a different web port, set AUTH_URL/NEXTAUTH_URL and the GitHub OAuth callback URL to that same origin; otherwise GitHub will return to the wrong local port.

The local dev, migration, seed, and integration-test commands default to the Docker PostgreSQL URL. Export DATABASE_URL in the shell only when you deliberately want to target another database; an older value in .env.local does not override the local default.

During onboarding, register a repository using either owner/repository or its full https://github.com/owner/repository URL. Intertool stores the normalized repository name; it does not clone or read the repository.

Connect AI clients

Create a token from API tokens and export it locally. Create a separate token for each client so you can revoke one connection without interrupting the others.

For agent-guided setup, paste this into Codex, Claude Code, Copilot, Grok, or another capable coding agent:

Install the Intertool MCP for me. Read and follow the canonical instructions at https://intertool.sh/install

The client selector on the Intertool homepage prepares this prompt for Claude Code, Codex, GitHub Copilot, Grok, or another MCP client and links directly to the matching manual setup below.

The /install endpoint returns plain Markdown designed for agents. It tells the agent how to detect its client, merge Intertool into existing MCP configuration without overwriting other servers, keep token plaintext out of chat and git, and verify the installed tools.

ChatGPT desktop and Codex

The ChatGPT desktop app, Codex CLI, and Codex IDE extension share the MCP servers configured in ~/.codex/config.toml:

[mcp_servers.intertool]
url = "http://localhost:3001/mcp"
bearer_token_env_var = "INTERTOOL_API_TOKEN"

Restart the app or extension, then use /mcp to confirm the connection.

Claude Code

Add .mcp.json to the target repository:

{
  "mcpServers": {
    "intertool": {
      "type": "http",
      "url": "${INTERTOOL_URL:-http://localhost:3001}/mcp",
      "headers": {
        "Authorization": "Bearer ${INTERTOOL_API_TOKEN}"
      }
    }
  }
}

export INTERTOOL_API_TOKEN="itk_..."

Run /mcp in Claude Code to inspect the connection. Never commit the token.

GitHub Copilot

Copilot CLI can register the local server directly:

copilot mcp add --transport http \
  --header "Authorization: Bearer $INTERTOOL_API_TOKEN" \
  intertool http://localhost:3001/mcp

For Copilot cloud agent, add the deployed Intertool MCP endpoint in Repository settings → Copilot → MCP servers. Store the token as an Agents secret whose name begins with COPILOT_MCP_; do not put token plaintext in the MCP JSON.

Grok and other remote clients

In Grok, open Connectors, create a custom MCP connector, and enter your deployed Intertool /mcp URL with bearer-token authentication. Grok runs remotely and cannot reach localhost, so use a public HTTPS deployment or a secure tunnel.

Any MCP client that supports Streamable HTTP can connect to the same /mcp endpoint by sending Authorization: Bearer itk_....

Import your Codex memory

The same personal token can import the durable Markdown memory stored by Codex on this computer:

export INTERTOOL_API_TOKEN="itk_..."
pnpm memory:import:codex

Open My memory in the dashboard to search the imported documents. The import is private to your user and idempotent; run it again whenever local Codex memory changes. It does not publish anything to Team memory. See Personal memory for the exact boundary and source options.

Plugin

claude-plugin/ contains the Intertool plugin. It adds the MCP server, context-retrieval guidance, a short SessionStart instruction, and /intertool:remember.

claude plugin validate ./claude-plugin

Getting Started