# MCP Server - Grep Developers

MCP Server Card, streamable HTTP endpoint, OAuth protected-resource metadata, and public v2 tool coverage.

Remote MCP discovery

# Grep exposes research as an MCP server.

Agents can discover the public v2 MCP endpoint, negotiate OAuth through protected-resource metadata, and call focused tools for research jobs, files, attachments, quota, and billing.

json

```
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json",
  "version": "1.0",
  "protocolVersion": "2025-06-18",
  "serverInfo": {
    "name": "grep-public-api-v2",
    "title": "Grep Public API v2 MCP",
    "version": "1.0.0"
  },
  "transport": {
    "type": "streamable-http",
    "endpoint": "https://api.grep.ai/api/v2/mcp"
  },
  "auth": {
    "type": "oauth2",
    "resource_metadata_url": "https://api.grep.ai/.well-known/oauth-protected-resource/api/v2/mcp"
  }
}
```

Discovery

## Where agents should look first.

The MCP Server Card is public, cacheable, and CORS-readable. OAuth metadata is separate so clients can discover authorization before sending a tool request.

[MCP Server Card](/.well-known/mcp/server-card.json)

Canonical public MCP discovery document for clients that probe the Cloudflare readiness path.

[MCP JSON alias](/.well-known/mcp.json)

Compatibility alias for clients that still probe the draft mcp.json location.

[OAuth protected resource](/.well-known/oauth-protected-resource/api/v2/mcp)

RFC 9728 metadata for the MCP resource and accepted scopes.

[Markdown twin](/developers/mcp.md)

Crawler-friendly MCP setup notes for agents that prefer Markdown.

Tools

## The MCP surface maps to public v2.

### Research jobs

Create, continue, cancel, list, and inspect Grep research jobs through MCP tool calls.

### Files and artifacts

List generated files, read text artifacts inline, and hand off large artifacts through signed URLs.

### Attachments

Create, read, and delete research attachments for file-backed research workflows.

### Custom experts

Create, configure, and maintain custom experts headlessly: skills, tools, context files, structured output, versions, and sharing.

### Quota and billing

Check quota, usage, and billing transactions before launching expensive research.

### Streamable HTTP

Use the public remote MCP endpoint over the current streamable HTTP transport.

### OAuth resource metadata

Discover the protected resource, scopes, and authorization server before attempting connection.

Connect

## Add Grep to your agent.

Choose your client below. Every option connects to the same streamable HTTP endpoint and uses the same browser-based OAuth flow.

### Connection essentials

- Server URL

  https\://api.grep.ai/api/v2/mcp

- Transport

  Streamable HTTP

- Authentication

  OAuth in your browser; no API key needs to be pasted into a client.

![Claude Code logo](/images/marketing/logos/mcp/claude-code.png)

### Claude Code

Anthropic's terminal-based coding agent.

#### Connect instructions

1. Open a terminal in the project where you want Grep available.
2. Run both commands below to add the remote HTTP server and start OAuth.
3. Complete sign-in in your browser, then run /mcp in Claude Code to verify the connection.

bash

```
claude mcp add --transport http grep https://api.grep.ai/api/v2/mcp
claude mcp login grep
```

[Official docs](https://code.claude.com/docs/en/mcp)

![Claude logo](/images/marketing/logos/mcp/claude.svg)

### Claude, Cowork & Claude Desktop

One remote connector works across Claude's web and desktop clients.

#### Connect instructions

1. Open Customize → Connectors, select +, then choose Add custom connector.
2. Name the connector Grep AI and paste the server URL below.
3. Select Add, then Connect, and complete OAuth in your browser.
4. Enable Grep AI from the Connectors menu when you start a conversation.

text

```
https://api.grep.ai/api/v2/mcp
```

[Official docs](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

![ChatGPT logo](/images/marketing/logos/mcp/chatgpt.png)

### ChatGPT

Custom MCP apps for supported ChatGPT workspaces.

#### Connect instructions

1. Confirm that your workspace admin has enabled Developer mode for your account.
2. Open Settings → Apps → Create and enter Grep AI as the app name.
3. Paste the server URL below, select OAuth, then choose Scan tools and complete authorization.
4. Select Create, then enable Grep AI from the Apps menu in a new chat.

text

```
https://api.grep.ai/api/v2/mcp
```

[Official docs](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta)

![Codex logo](/images/marketing/logos/mcp/codex.png)

### Codex CLI

OpenAI's terminal coding agent.

#### Connect instructions

1. Open a terminal in the project where you want Grep available.
2. Run both commands below to add the streamable HTTP server and start OAuth.
3. Complete sign-in in your browser, then run codex mcp list or /mcp in Codex to verify the connection.

bash

```
codex mcp add grep --url https://api.grep.ai/api/v2/mcp
codex mcp login grep
```

[Official docs](https://developers.openai.com/codex/mcp)

Experts

## Build an expert headlessly.

Everything the Agent Builder UI does is available as MCP tools (and mirrored at<!-- --> `/api/v2/experts`), gated by the<!-- --> `experts:read` and<!-- --> `experts:write` scopes.

`skills_list / skill_get / skill_create`

Browse the skill catalog, read any SKILL.md, and author custom skills.

`mcp_tools_list`

List the MCP tools an expert can be granted.

`expert_apply`

Declarative Terraform-style sync: one manifest, one call — diffs desired vs current state (skills, config, context files) and performs the minimal delta. Idempotent; dry\_run returns the plan.

`expert_create / expert_get / expert_update / expert_delete / expert_list`

Imperative lifecycle with the complete Builder config: output schema, SOP, input form, defaults, cost cap.

`expert_build_start / expert_build_get`

Alternative entry point: describe a domain and a builder agent designs the expert; poll to completion.

`expert_context_file_upload / expert_context_files_list / expert_context_file_get / expert_context_file_delete`

Attach reference documents — by source\_url (server-side SSRF-guarded fetch, preferred), attachment\_id, or inline base64. Archives are rejected (upload the members).

`expert_versions_list / expert_version_get / expert_version_restore`

Every change is snapshotted; restores are reversible.

`expert_extract_config / expert_generate_workflow / expert_plan_preview`

Preview config extraction, workflow authoring, and the research plan your SOP would produce — planning phase only, cents instead of full runs.

`expert_share / expert_unshare / expert_shares_list / expert_set_visibility`

Share with a user, an email domain, or a team.

`key_create / key_list / key_revoke`

Mint, inspect, and revoke your own parcha- API keys headlessly. A key's scopes are a subset of your OAuth token's; the secret is returned once, at creation.

`batch_create / batch_list / batch_get / batch_cancel / batch_retry_row / batch_estimate`

Run research at scale: one batch fans out up to 100 questions as parallel research jobs under one handle — estimate the credit cost, poll progress, read each row's report via research\_get, retry failed rows.

### 1. Discover skills and tools

json

```
skills_list { "query": "financial analysis", "limit": 20 }
mcp_tools_list { "category": "screening" }
```

Filter server-side (query/category/server/limit) — the response's total tells you when to refine instead of paging. Tools flagged always\_on ride with every run and need no grant. Author a bespoke skill if the catalog lacks one:

json

```
skill_create {
  "name": "credit-memo-writer",
  "description": "Writes a five-field credit memo from spread financials.",
  "content": "# Credit Memo Writer\n\nMethodology..."
}
```

### 2. Create the expert with structured output

json

```
expert_create {
  "name": "Merchant Credit Analyst",
  "system_prompt": "You are a credit analyst. Spread the financials...",
  "skill_names": ["credit-memo-writer", "financial-data-research"],
  "mcp_tool_names": ["parallel:web_search"],
  "output_schema": {
    "type": "object",
    "properties": { "icr": { "type": "integer", "minimum": 1, "maximum": 10 } },
    "required": ["icr"]
  },
  "input_form": [{ "label": "Company name", "type": "text", "required": true }],
  "max_cost_usd": 5.0
}
```

Supplying output\_schema / output\_sop makes structured output deterministic — no LLM extraction pass.

### 3. Attach context files (by URL, attachment, or inline)

json

```
expert_context_file_upload {
  "expert_id": "<id from step 2>",
  "source_url": "https://acme.example/chart-of-accounts.pdf"
}
expert_context_file_upload {
  "expert_id": "<id>",
  "attachment_id": "<research attachment id>"
}
expert_context_files_list { "expert_id": "<id>" }
```

Prefer source\_url — the server fetches it (public http(s) only, SSRF-guarded, size-capped), so the bytes never transit your context window. attachment\_id copies from a research attachment you own; content\_base64/content\_text remain for small inline files. Expand .zip archives client-side — the server rejects them.

### 4. Validate and iterate cheaply

json

```
expert_create { ..., "validate_only": true }
expert_update { "expert_id": "<id>", "system_prompt": "...v2...", "validate_only": true }
expert_plan_preview { "expert_id": "<id>", "question": "Spread FY2025 for Acme" }
expert_update { "expert_id": "<id>", "system_prompt": "...v2..." }
```

validate\_only runs every check (skill/tool names, output\_schema validity, template existence) without persisting; expert\_plan\_preview runs only the planning phase so SOP edits cost cents, not runs. The MCP schemas enumerate valid input\_form types and output\_type keys — no 422 archaeology. expert\_update is a partial patch and every change lands in the version history.

### Or: one manifest, one call

json

```
expert_apply {
  "manifest": {
    "name": "Merchant Credit Analyst",
    "system_prompt": "You are a credit analyst...",
    "skills": ["credit-memo-writer", "financial-data-research"],
    "custom_skills": [{ "name": "credit-memo-writer", "description": "...", "content": "# ..." }],
    "mcp_tool_names": ["parallel:web_search"],
    "output_schema": { "type": "object", "properties": { "icr": { "type": "integer" } } },
    "context_files": [
      { "name": "chart-of-accounts.pdf", "source_url": "https://acme.example/chart.pdf" },
      { "name": "icr-scale.md", "content": "1 to 10..." }
    ]
  },
  "dry_run": true
}
```

expert\_apply replaces steps 1–4: it diffs the manifest against current state and performs the minimal create/update/upload/delete set — custom skills included. Re-applying an unchanged manifest is a no-op; drop dry\_run to apply.

### 5. Run it

json

```
research_create {
  "question": "Spread FY2025 financials for Acme Corp",
  "expert_id": "<id>",
  "effort": "high"
}
```

The run stages the expert's context files into the sandbox and returns structured output matching the schema.

Discover

## Fetch the Server Card.

bash

```
curl https://grep.ai/.well-known/mcp/server-card.json | jq
```

Authorize

## Resolve OAuth metadata.

bash

```
curl https://grep.ai/.well-known/oauth-protected-resource/api/v2/mcp | jq
```

Connect

## Point MCP clients at v2.

json

```
{
  "mcpServers": {
    "grep": {
      "url": "https://api.grep.ai/api/v2/mcp"
    }
  }
}
```

## Give agents tool access without a browser.

Use REST and OpenAPI for direct integrations. Use MCP when an agent client wants tools, OAuth discovery, and a standard remote transport.

[Server Card](/.well-known/mcp/server-card.json)[v2 reference](/developers/api/v2)