Research Tools (MCP)

IAS agents can use Model Context Protocol (MCP) servers as external research tools -- services like Perplexity for web search, Context7 for documentation lookup, and Firecrawl for web scraping. MCP integration is optional and lightweight. When enabled, agents typically make 1--3 focused research calls per task to gather context before acting.

MCP is primarily used by the Researcher role within the IAS framework. The pattern is intentional: a small call budget, distilled results written to repo notes, and no large data dumps pasted into the main agent thread.

How MCP works in IAS

MCP configuration has two layers that work together:

1. Workspace defaults -- configured in the Console. These define which MCP servers your workspace uses, what the call budget is, and how the configuration gets written into repos during Build Context.
2. Local runtime setup -- configured on your machine. API keys and secrets for MCP servers live locally and are never stored in the cloud.

This separation exists for a reason: the Console knows which tools the workspace uses, but the secrets needed to authenticate with those tools stay on developer machines. The Console never sees or stores your MCP API keys.

Configuring workspace defaults

1. Open the Command Center and go to Settings.
2. Select the MCP tab.
3. Choose a preset or configure custom servers:

4. Click Save workspace defaults.

The saved configuration is stored in workspaces.mcpPolicy and gets included when you bootstrap IAS into a repository via Build Context.

Advanced settings

Under the advanced section you can configure:

• Intended use -- restrict MCP to research only (recommended) or allow broader usage. Research-only mode encourages agents to gather information without modifying external systems.
• Max calls per task -- limit how many MCP calls an agent can make per task. The default is 3, with a maximum of 10. This prevents runaway usage and encourages agents to be selective about which questions they research externally.

What happens during Build Context

When you run Build Context for a target repository, the workspace MCP defaults are written into the repo's IAS scaffolding:

• docs/ias/project-context.md receives:
  • mcp_pack -- which preset is active
  • mcp_budget_calls_per_task -- the per-task call limit
  • preferred_mcp_servers -- the list of configured servers
• Optionally, a .mcp.json file is generated with metadata-only server templates (names and URLs, no secrets) when enabled during context configuration.

This means every developer working on the repo sees the same MCP configuration, and agents bootstrapped from the repo know which tools are available without any per-developer setup beyond providing API keys.

Local runtime setup

After workspace defaults are configured, you need to set up the actual MCP servers on your local machine. This is where API keys live.

Claude Code

For Claude Code, configure MCP servers via the CLI or by editing .mcp.json in your project root.

Perplexity (stdio):

claude mcp add --scope project perplexity \
  --env PERPLEXITY_API_KEY="your-api-key" \
  -- npx -y @perplexity-ai/mcp-server

Context7 (remote HTTP):

claude mcp add --scope project --transport http context7 \
  https://mcp.context7.com/mcp \
  --header "CONTEXT7_API_KEY: your-api-key"

Context7 (local stdio):

claude mcp add --scope project context7 \
  -- npx -y @upstash/context7-mcp --api-key your-api-key

Codex CLI

For Codex CLI, configure MCP servers in ~/.codex/config.toml.

HTTP servers (e.g., Context7):

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"

[mcp_servers.context7.http_headers]
CONTEXT7_API_KEY = "your-api-key"

Stdio servers (e.g., Perplexity):

codex mcp add perplexity \
  --env PERPLEXITY_API_KEY="your-api-key" \
  -- npx -y @perplexity-ai/mcp-server

Other runtimes

IAS works with any agent runtime that supports MCP. The Console generates copy/paste commands and config snippets under Settings > MCP to simplify setup for supported runtimes.

Environment variables

Each MCP server requires its own API key, set as an environment variable on the machine where agents run:

Set these in your shell profile (.bashrc, .zshrc, etc.) or pass them directly when starting the agent. Do not commit them to your repository.

Supported servers

IAS works with any MCP-compatible server. The built-in presets include:

You can add custom servers by selecting the Custom preset in Settings and defining your own server entries with a name, transport type (HTTP or stdio), and URL.

When to use which server

Choosing the right MCP server for a research task makes the difference between a useful result and wasted budget:

• Use Perplexity when agents need to answer broad questions ("What are the best practices for X?"), find current information about libraries or APIs, or understand how other teams have solved similar problems. Perplexity synthesizes results from multiple web sources into a coherent answer.
• Use Context7 when agents need version-specific documentation for a library or framework. Instead of searching the web and potentially finding outdated answers, Context7 retrieves documentation pinned to the exact version your project uses.
• Use Firecrawl when agents need the full content of a specific web page -- for example, extracting a migration guide, changelog, or API reference from a known URL. Firecrawl handles JavaScript-rendered pages and returns clean, structured content.

For most teams, the Research Pro preset (all three servers) provides the best coverage. If your work is primarily code-focused and you rarely need web search, DevDocs (Context7 only) keeps things minimal.

Safety and privacy

MCP in IAS follows a strict security model designed to keep your data safe:

• API keys stay local. Keys are stored on your machine in environment variables or local config files. They are never sent to the Console, never stored in the Convex backend, and never committed to Git. If IAS generates a .mcp.json template in your repo, it contains server names and URLs only -- no secrets.
• Research-only by default. The recommended configuration restricts MCP to research use: web search, documentation lookup, and page extraction. Agents do not use MCP to modify external systems or write data to third-party services.
• Bounded usage. The maxCallsPerTask setting caps how many MCP calls an agent can make per task. This prevents runaway usage, controls costs, and encourages agents to be deliberate about when they reach out to external tools.
• Distilled results. Agents are instructed to distill MCP results into concise repo notes rather than pasting large raw outputs into the main conversation thread. This keeps the context window focused and avoids noise.
• No proprietary code leakage. Avoid configuring MCP tools in ways that would send proprietary source code or trade secrets to external services. MCP calls should be limited to research queries (questions, documentation lookups) rather than code analysis.