Installation - Coval Documentation

Hosted Connector (Recommended)

The hosted connector is always up to date and does not require an API key in client configuration. It uses OAuth to bind the connection to your Coval user and the organization you select. Server URL: https://mcp.coval.dev/mcp

ChatGPT
Claude
Codex
Other MCP clients

Open the Coval plugin in ChatGPT and select Install plugin.Complete the Coval sign-in flow, choose an organization, and approve access. Start a new chat, enable Coval if needed, and ask it to list your Coval agents.Plugin availability can depend on your ChatGPT plan and workspace settings. In a managed workspace, an administrator may need to allow Coval before members can install or use it.

Open Coval in the Claude connector directory and select Connect. Coval appears with a Community label in the directory.Complete the Coval sign-in flow, choose an organization, and approve access.If the directory listing is unavailable in your workspace, add Coval as a custom connector:

Team and Enterprise: an organization Owner opens Organization settings > Connectors, selects Add > Custom > Web, and enters https://mcp.coval.dev/mcp. Each member then opens Customize > Connectors, finds Coval, and selects Connect.
Free, Pro, and Max: open Customize > Connectors, select + > Add custom connector, and enter https://mcp.coval.dev/mcp.

Add and authorize the connector from a terminal:

codex mcp add coval --url https://mcp.coval.dev/mcp
codex mcp login coval

If your Codex installation does not recognize mcp login, update it with codex update and run the login command again.Complete the browser authorization flow, then start a new Codex task. The connection is shared with Codex Desktop when both use the same Codex configuration directory.

Add https://mcp.coval.dev/mcp as a remote Streamable HTTP server and complete the browser authorization flow. The client must support OAuth discovery and dynamic client registration.

The organization selected during authorization determines which Coval data and tools the assistant can access. To change organizations, disconnect Coval in the assistant, switch to the target organization in Coval, and reconnect. If the browser reuses the previous authorization, sign out of Coval in that browser session before reconnecting.

Local Server (API Key)

Run the npm package locally when you need a custom API endpoint, service-account style access, or local development. The local transport uses a Coval API key rather than interactive OAuth.

COVAL_API_KEY=your_api_key_here npx -y @coval/mcp-server

Example local MCP configuration:

{
  "mcpServers": {
    "coval": {
      "command": "npx",
      "args": ["-y", "@coval/mcp-server"],
      "env": {
        "COVAL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Create and manage API keys from Coval Settings.

Local Environment Variables

Variable	Required	Default	Description
`COVAL_API_KEY`	Yes	-	Coval API key used by the local stdio server
`COVAL_API_BASE_URL`	No	`https://api.coval.dev/v1`	Custom API endpoint
`LOG_LEVEL`	No	`info`	Logging level

Local Development

git clone https://github.com/coval-ai/mcp-server
cd mcp-server
npm install
npm run build
export COVAL_API_KEY=your_api_key_here
npm start

Test the local server interactively with MCP Inspector:

npm run inspector

​Hosted Connector (Recommended)

​Local Server (API Key)

​Local Environment Variables

​Local Development

Hosted Connector (Recommended)

Local Server (API Key)

Local Environment Variables

Local Development