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.

Server Card OAuth metadata OAuth guide

/.well-known/mcp/server-card.jsonMCP 2025-06-18

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

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

MCP JSON alias

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

OAuth protected resource

RFC 9728 metadata for the MCP resource and accepted scopes.

Markdown twin

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.

Claude Code

Anthropic's terminal-based coding agent.

Connect instructions

Open a terminal in the project where you want Grep available.
Run both commands below to add the remote HTTP server and start OAuth.
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

Claude, Cowork & Claude Desktop

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

Connect instructions

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

text

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

Official docs

ChatGPT

Custom MCP apps for supported ChatGPT workspaces.

Connect instructions

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

text

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

Official docs

Codex CLI

OpenAI's terminal coding agent.

Connect instructions

Open a terminal in the project where you want Grep available.
Run both commands below to add the streamable HTTP server and start OAuth.
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

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 v2 reference