MCP Servers

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.

Basic MCP Server

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

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

const qaAgent = agent({
  id: "qa-agent",
  tenantId: "your-tenant",
  name: "QA Agent",
  tools: {
    knowledge_base: knowledgeBaseTool,
  },
});

Authentication

MCP servers 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 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.

Example with Authentication

import { mcpTool, credential } from "@inkeep/agents-sdk";
import { CredentialStoreType } from "@inkeep/agents-core";

const apiKeyTool = mcpTool({
  id: "weather-api",
  name: "weather",
  description: "Get weather information",
  serverUrl: "https://api.weather.com/mcp",
  credential: credential({
    id: "weather-api-credential",
    type: CredentialStoreType.memory,
    credentialStoreId: "memory-default",
    retrievalParams: {
      key: "WEATHER_API_KEY",
    },
  }),
});

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

Selective 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
});

Best Practices

To ensure agents properly utilize their tools, follow these best practices:

Give tools clear, descriptive names and descriptions - Explain what the tool does and when it should be used
Reference the tool in the agent's prompt - Explicitly mention that the agent has access to specific tools and describe scenarios where they should be used
Secure your credentials - Store sensitive information using the credential system
Limit tool scope - Use activeTools to expose only necessary functionality

Example with best practices applied:

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

const productTool = mcpTool({
  id: "product-tool",
  name: "product",
  description: "Search product information, pricing, and specifications",
  serverUrl: "https://mcp.inkeep.com/inkeep/mcp",
  activeTools: ["search_products", "get_pricing", "get_specifications"], // Only enable needed tools
});

const productAgent = agent({
  id: "product-agent",
  name: "Product Agent",
  description: "Answers questions about the Inkeep product",
  prompt: `You are a product specialist for Inkeep. You have access to the product tool to search for:
  - Product features and specifications
  - Pricing information
  - Technical documentation
  - Integration guides
  
  Use the product tool when customers ask about features, pricing, or technical details.
  If questions are outside the Inkeep product scope, transfer to the router agent.`,
  tools: {
    product: productTool,
  },
  canTransferTo: () => [routerAgent],
});