Register MCP Servers as Tools

MCP tools connect to external MCP servers, enabling integration with a wide ecosystem of tools and services. Registering them as tools is a two step process:

Step 1: Get an MCP server URL

You need access to an MCP server before you can use its tools. Learn about connecting to Native servers, using Composio, using Gram, or building Custom servers in the MCP Servers tutorial.

Step 2: Register the MCP server as a tool in your agent

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

// Register an existing MCP server as a tool
const knowledgeBaseTool = mcpTool({
  id: "knowledge-base-tool",
  name: "knowledge_base",
  description: "Search the company knowledge base for information",
  serverUrl: "https://kb.yourcompany.com/mcp", // URL of your deployed MCP server
});

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" } 
    })],
});

Environment-Aware MCP Servers

You can also configure MCP tools to switch based on your environment. This is useful when you want to use different MCP tool configurations for development vs production.

Creating environment-aware MCP tools is a two step process:

Step 1: Define environment configurations

Step 2: Use the MCP tool in your sub agent

projects/my-project/agents/customer-support-agent.ts

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')],
});

This pattern is useful if you want to keep track of different credentials for different environments. When you push your project using the Inkeep CLI inkeep push command with the --env flag, the credentials will be loaded from the appropriate environment file. For example, if you run inkeep push --env development, the credentials will be loaded from the environments/development.env.ts file.

CLI Environment Variables

The CLI respects these environment variables when using the --env flag:

# Set environment name via environment variable
export INKEEP_ENV=production
inkeep push  # Uses production environment automatically

# Override via CLI (takes precedence)
inkeep push --env development  # Uses development instead

On this page