Skip to content

MCP Integration

Learn how to integrate Model Context Protocol (MCP) servers into your agent specifications.

Model Context Protocol (MCP) enables agents to connect to external data sources and services through standardized server integrations. Agent Script Tools provides built-in support for defining and validating MCP integrations.

MCP Server Declaration

Frontmatter Tools

Declare MCP tools in the frontmatter using the naming pattern mcp__server-name__tool-name:

YAML
1
2
3
4
5
6
---
name: research-agent
description: AI agent with research capabilities
tools: read, write, mcp__context7__get-library-docs, mcp__sequential-thinking__analyze
model: claude-3-5-sonnet
---

Automatic Server Detection

The system automatically extracts MCP server names from tool patterns:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
from agent_script_spec.models import Frontmatter

frontmatter = Frontmatter(
    name="research-agent",
    description="AI agent with research capabilities",
    tools={
        "read", "write", 
        "mcp__context7__get-library-docs",
        "mcp__context7__resolve-library-id", 
        "mcp__sequential-thinking__analyze"
    },
    model="claude-3-5-sonnet"
)

# Automatically extracted server names
print(frontmatter.mcp_server_names)
# Output: ["context7", "sequential-thinking"]

MCP Integration Section

Define how each MCP server is used in the specification:

Markdown
1
2
3
4
### MCP Integration

* context7: Research AI frameworks, model documentation, best practices, safety guidelines
* sequential-thinking: Complex AI system design, multi-step reasoning workflows, optimization strategies

Validation Requirements

Server Consistency

MCP integration keys must match the servers extracted from frontmatter tools. The system validates this automatically:

  • ✅ Valid: Integration keys match extracted servers
  • ❌ Error: Extra servers not present in tools
  • ⚠️ Warning: Missing servers present in tools but not in integration

Common MCP Servers

Research & Documentation

Purpose: Access to library documentation and AI frameworks

Tools:

Text Only
1
2
mcp__context7__get-library-docs
mcp__context7__resolve-library-id

Usage:

Markdown
1
* context7: Research AI frameworks, model documentation, best practices

Purpose: GitHub repository documentation and analysis

Tools:

Text Only
1
2
3
mcp__deepwiki__read-wiki-structure
mcp__deepwiki__read-wiki-contents
mcp__deepwiki__ask-question

Reasoning & Analysis

Purpose: Complex multi-step reasoning workflows

Tools:

Text Only
1
mcp__sequential-thinking__sequentialthinking

Usage:

Markdown
1
* sequential-thinking: Complex AI system design, multi-step reasoning workflows

Purpose: Web search and content retrieval

Tools:

Text Only
1
2
3
mcp__brave-search__web-search
mcp__brave-search__local-search
mcp__brave-search__news-search

Integration Examples

Research Assistant

YAML
1
2
3
4
5
6
---
name: ai-research-assistant
description: Advanced AI research and analysis agent
tools: read, write, mcp__context7__get-library-docs, mcp__sequential-thinking__analyze
model: claude-3-5-sonnet
---
Markdown
1
2
3
4
### MCP Integration

* context7: Access latest AI research papers and framework documentation
* sequential-thinking: Multi-step analysis for complex research questions

Data Analysis Agent

YAML
1
2
3
4
5
6
---
name: data-analyst
description: Specialized data analysis and visualization agent
tools: pandas, matplotlib, mcp__context7__resolve-library-id, mcp__brave-search__web-search
model: claude-3-5-sonnet
---
Markdown
1
2
3
4
### MCP Integration

* context7: Python data science library documentation and best practices
* brave-search: Research industry trends and external datasets

Best Practices

Tool Naming

Consistent Naming

Use clear, descriptive server names in the MCP tool pattern:

Text Only
1
2
3
4
5
6
7
# Good
mcp__context7__get-library-docs
mcp__research-db__query-papers

# Avoid
mcp__ctx__docs
mcp__db1__query

Integration Descriptions

Provide clear descriptions of how each MCP server enhances the agent:

Markdown
1
2
3
4
5
# Good - Specific and actionable
* context7: Access comprehensive documentation for Python ML libraries including scikit-learn, TensorFlow, and PyTorch

# Less helpful - Too vague  
* context7: Get documentation

Server Dependencies

Document when MCP servers work together:

Markdown
1
2
3
4
5
### MCP Integration

* context7: Primary documentation source for AI frameworks and libraries
* sequential-thinking: Complex reasoning workflows that leverage context7 research findings
* brave-search: External validation and supplementary research for context7 findings

Next Steps