MCP Tools

MCP tools connect to external servers that implement the MCP standard. This allows you to integrate with a wide ecosystem of existing tools and services.

Creating MCP tools is a two step process:

Step 1: Get an MCP server URL

Creating an MCP server is covered in the How to create MCP servers tutorial.

Step 2: Create an MCP tool and use it in your sub agent

import { subAgent, mcpTool } from "@inkeep/agents-sdk";

const knowledgeBaseTool = mcpTool({
  id: "knowledge-base-tool",
  name: "knowledge_base",
  description: "Search the company knowledge base for information",
  serverUrl: "https://kb.yourcompany.com/mcp",
});

const qaAgent = subAgent({
  id: "qa-agent",
  name: "QA Agent",
  description: "Responsible for answering questions about the company knowledge base.",
  prompt: `You are a Question-Answer agent that can answer questions about the company knowledge base. You have access to the knowledge base tool to search for information.`,
  canUse: () => [knowledgeBaseTool],
});

Note

Tip: When adding tools to an agent, you can also reference the tool in the agent's prompt to help the agent understand how to use the tool.

Authentication

If your MCP server requires authentication, we support various authentication methods (via credentials):

No Authentication - For public APIs or internal services
API Key - For services requiring API keys
Bearer Token - For JWT or similar token-based authentication
Token Authentication - For custom token schemes
OAuth Flows - For standard OAuth 2.0 authentication
OAuth 2.1 Flows - For modern OAuth 2.1 "1-click" authentication

For OAuth flows and OAuth 2.1 flows, it's recommended to use the Visual Builder for easier configuration.

See Credentials for detailed examples and implementation guidance for each authentication type.

Custom Headers

You can configure custom headers for your MCP server requests. Use credentials for sensitive information (API keys, tokens) and headers for non-sensitive metadata (user agent, version info, etc.).

import { mcpTool } from "@inkeep/agents-sdk";

const customHeadersTool = mcpTool({
  id: "enterprise-api",
  name: "enterprise_data",
  description: "Enterprise API with custom headers",
  serverUrl: "https://enterprise.example.com/mcp",
  headers: {
    "User-Agent": "Inkeep-Agent/1.0",
    "X-Client-Version": "2024.1",
  },
});

Selecting Tools

Selective Tool Activation

Enable only specific tools from a server using MCP Server tool names in the activeTools field.

import { mcpTool } from "@inkeep/agents-sdk";

const selectiveTool = mcpTool({
  id: "limited-server",
  name: "analytics_readonly",
  description: "Analytics server with limited access",
  serverUrl: "https://analytics.example.com/mcp",
  activeTools: ["get_metrics", "generate_report"], // Only these tools
});

Using `with` for Tool Selection

While activeTools in mcpTool limits which tools are available from the server, you can further refine tool access at the sub agent level using mcpTool.with. This allows different agents to use different subsets of tools from the same MCP server.

import { agent, mcpTool } from "@inkeep/agents-sdk";

// Define the MCP server with all available tools
const customerSupportTool = mcpTool({
  id: "customer-support-tool",
  name: "Customer Support Tool",
  description: "Customer Support Tool",
  serverUrl: "https://customer-support.example.com/mcp",
});

// Agent that only uses specific tools from the server
const customerSupportAgent = subAgent({
  id: "customer-support-agent",
  name: "Customer Support Agent",
  description: "Responsible for customer support",
  prompt: "You are a helpful assistant",
  canUse: () => [customerSupportTool.with({ 
      selectedTools: ["customer-support-tool"], 
      headers: { "X-Custom-Header": "custom-value" } 
    })],
});

import { subAgent } from "@inkeep/agents-sdk";
import { envSettings } from "../environments";

const customerSupportAgent = subAgent({
  id: "customer-support-agent",
  name: "Customer Support Agent",
  description: "Responsible for customer support",
  prompt: "You are a helpful assistant",
  canUse: () => [envSettings.getEnvironmentMcp('customer_support_tool')],
});

Step 1: Get an MCP server URL

Step 2: Create an MCP tool and use it in your sub agent

Authentication

Custom Headers

Selecting Tools

Selective Tool Activation

Using `with` for Tool Selection

Environment-Aware MCP Servers

Step 1: Define environment configurations

Step 2: Use the MCP tool in your sub agent

On this page