> ## Documentation Index > Fetch the complete documentation index at: https://lib.findy.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # What is MCP? Connecting AI agents to external tools > Model Context Protocol is an open standard that connects AI applications to external data sources, tools, and workflows. ## Overview MCP, short for Model Context Protocol, is an open standard for connecting AI applications to external systems. Through MCP, an AI agent can reach data sources such as files, databases, and repositories, tools such as search engines and issue trackers, and workflows such as specialized prompts — the context and actions it needs to do real work. Think of MCP as a USB-C port for AI applications. Just as USB-C gives devices one standardized connector for many peripherals, MCP gives an AI application one standardized way to connect to many external systems, without inventing a custom integration format for each pair. The scope of MCP is the boundary between an agent and the outside world. It is not a workflow design method, a permission model by itself, or a replacement for clear instructions. Those concerns still need to be designed around the agent. MCP provides the integration layer those designs can stand on. This page explains why MCP matters, what it consists of, which adoption option fits which situation, and what to consider when operating MCP servers as a team. ## Why MCP AI agents become useful when they can act on the systems where work actually happens. Connected through MCP, an agent can, for example: * Read your calendar and team documents and act as a personalized assistant * Generate a working application from a design file * Answer questions by analyzing data across an organization's databases Without a shared protocol, each AI application has to integrate with each tool directly, and every new agent-tool pair becomes another custom adapter. MCP is an open standard: a tool or data source exposes one MCP server, and any MCP-supporting client can connect to it — build once, integrate everywhere: ```mermaid theme={null} flowchart LR A1[AI application] --> C[MCP client] C --> S1[MCP server: repository] C --> S2[MCP server: issue tracker] C --> S3[MCP server: database] ``` The benefits differ by where you stand in the ecosystem: | Perspective | Benefit | | --------------- | ------------------------------------------------------------------------------------------- | | Developers | Less time and complexity when building or integrating an AI application or agent. | | AI applications | Access to an ecosystem of data sources, tools, and apps that expands what the agent can do. | | End users | More capable AI applications that can reach their data and act on their behalf when needed. | The result is not an agent that can do anything. It is narrower and more practical: the agent can perform specific external operations that a server exposes and that the server and client control. ## Core concepts MCP is easiest to understand as a server-client model: servers expose three kinds of capability, and clients offer reverse-direction features such as elicitation. ### Server and client An MCP server exposes capabilities from a system. It may wrap a local command, a filesystem, an internal API, a SaaS product, a database, or a documentation index. The server is responsible for translating MCP requests into the system's native operations. An MCP client lives inside the AI application. It connects to one or more servers, lists what each server can provide, and makes those capabilities available to the agent according to the application's rules. The agent normally does not call the underlying service directly. It asks the client to use a capability, and the client sends the structured request to the server. This separation keeps integrations reusable. | Part | Role | | ---------- | --------------------------------------------------------------------------- | | MCP server | Owns the system-specific adapter and exposes a stable MCP surface. | | MCP client | Connects the AI application to servers and mediates what the agent can use. | | Agent | Selects and uses capabilities as part of solving a task. | ### Tools `tools` are callable actions. They are the part of MCP most similar to a function call: the server declares a tool name, description, input schema, and result shape, and the agent can request execution with structured arguments. Typical tools include: * Searching issues or pull requests * Creating a ticket * Running a query against an approved data source * Fetching logs for a service and time range * Triggering a narrow internal automation Good tools are specific enough to be safe and useful. A tool named `run_any_command` gives the agent too much surface area. A tool named `search_recent_deploy_errors` carries intent, scope, and expected input. At run time, the exchange looks like this: the agent picks the tool from the request, calls it with structured arguments, and answers from the result: ```text example theme={null} > did yesterday's api-gateway deploy throw any errors? ⏺ deploy-server - search_recent_deploy_errors (MCP)(service: "api-gateway", hours: 24) ⎿ ### Deploy errors: api-gateway (last 24h) total: 2 - 14:03 Migration timeout on users table - 14:11 Rollback triggered by health check ⏺ Yesterday's api-gateway deploy hit 2 errors: a migration timeout on the users table, followed by a rollback triggered by the health check. ``` ### Resources `resources` are readable context exposed by a server. They are useful when the agent needs data but should not have to call an action-oriented tool for every document or object. Examples include: * A file or directory tree * A design document * A runbook * A database schema * A generated summary of project state The client lists a server's resources and reads them by URI. The user can attach one to the conversation, or the agent can pull one in when the task needs it: ```text example theme={null} > what are the rollback steps? ⏺ deploy-server - resources/list (MCP) ⎿ file:///runbooks/deploy.md, file:///runbooks/oncall.md ⏺ deploy-server - resources/read (MCP)(uri: "file:///runbooks/deploy.md") ⎿ # Deploy runbook ## Rollback 1. Freeze deploys 2. Revert the release tag 3. Re-run health checks ⏺ Rollback takes three steps: freeze deploys, revert the release tag, and re-run the health checks before reopening the pipeline. ``` Resources should be shaped so the client can retrieve only the parts that matter. Dumping a whole documentation site into the agent's context defeats the purpose. Expose stable identifiers, meaningful metadata, and focused resource bodies. ### Prompts `prompts` are reusable prompt templates provided by a server. They package a known way to ask for work around the server's domain: investigate an incident, summarize a project, prepare a release note, or triage a class of alerts. A prompt shines when it encodes a multi-step procedure that drives the server's own tools. The client shows the server's prompts for the user to invoke. Invoking one expands the template into the agent's instruction, and the agent follows the steps: ```text example theme={null} > /investigate_deploy_failure api-gateway ⏺ deploy-server - search_recent_deploy_errors (MCP)(service: "api-gateway", hours: 24) ⎿ ### Deploy errors: api-gateway (last 24h) total: 2 ... ⏺ deploy-server - get_deploy_status (MCP)(service: "api-gateway") ⎿ release v2.14.1 deployed 13:58 ... ⏺ The errors started with v2.14.1, and the likely cause is the users table migration. Recommendation: roll back to v2.14.0 and re-run the migration off-peak. ``` ### Elicitation The three capabilities above flow from the server to the agent. Elicitation runs in the opposite direction: when a server needs information it cannot get on its own — a missing parameter, a credential, or confirmation before an action — it asks the user mid-task through the client. ```mermaid theme={null} sequenceDiagram participant U as User participant C as MCP client participant S as MCP server C->>S: tools/call S->>C: elicitation/create C->>U: Show dialog U->>C: Fill in and approve C->>S: Elicitation response S->>C: Tool result ``` The client renders the request to the user and returns the answer to the server. A server can ask in two forms: a form with fields the server defines, or a URL the user opens in the browser for authentication or approval. A form-mode request flows like this: ```text example theme={null} > roll back staging with deploy-server ⏺ deploy-server - rollback_release (MCP)(environment: "staging") deploy-server → elicitation/create message: "Roll back staging to v2.14.0?" fields: reason (string) user → accept { reason: "migration timeout" } ⎿ Rolled back staging to v2.14.0 (reason: migration timeout) ⏺ Staging is now rolled back to v2.14.0, with "migration timeout" recorded as the reason. ``` Elicitation keeps confirmation in the protocol instead of in tool design: rather than guessing missing inputs or executing a destructive operation silently, the server can stop and ask. ## How to adopt MCP Think of adoption in terms of what the client connects to. There are three shapes: an existing MCP server you launch locally, a remote MCP server you reach by URL, and a custom MCP server you build yourself. | Option | When it fits | | ------------------- | ----------------------------------------------------------------------------------------------- | | Existing MCP server | The tool you need ships a server you can launch locally with a single command. | | Remote MCP server | The server is hosted elsewhere — by a vendor or your own organization — and you connect by URL. | | Custom MCP server | The useful capability sits behind internal systems, so you build the server yourself. | ### Existing MCP servers Connect an existing MCP server when the tools your team already uses provide one. This is the lowest-cost option: no implementation, just configuration. Many MCP clients read a similar configuration shape — registering a server that needs credentials looks like this: ```json client configuration theme={null} { "mcpServers": { "example-server": { "command": "npx", "args": ["-y", "@example/mcp-server"], "env": { "EXAMPLE_API_TOKEN": "${EXAMPLE_API_TOKEN}" } } } } ``` Servers that need credentials receive them as environment variables through the `env` key — keep the actual secret values out of the configuration file. Evaluate an existing server by asking: * Does it expose the capabilities your agent actually needs? * Are the tool descriptions and schemas specific enough for reliable use? * Can authentication be scoped to real users, teams, and environments? * Does the server return concise results, or does it overfill the context? * Does the maintenance policy fit your organization? Existing servers deliver the most value with the least operational risk on read-heavy work: search, lookup, summarization, and context retrieval. ### Remote MCP servers Connect to a remote MCP server when the server is hosted elsewhere: an official server operated by a SaaS vendor, or one your organization runs for the whole team. Nothing runs locally — the client connects by URL and authenticates, typically with OAuth or an API key: ```json client configuration theme={null} { "mcpServers": { "deploy-server": { "type": "http", "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer ${DEPLOY_MCP_TOKEN}", "X-Organization": "${DEPLOY_MCP_ORG}" } } } } ``` As with existing servers, pass secrets by environment-variable reference — many clients support environment-variable expansion in their configuration. Hosting your own remote server gives the organization one place to manage: * Authentication and authorization — who can use which tools is controlled server-side, with no per-machine credentials to distribute * Server updates — everyone connects to the same deployment, so one update reaches the whole team and the tool set stays consistent * Audit logs and monitoring — every request passes through one place, so logging and observability centralize A vendor-hosted server costs you nothing to operate. Hosting your own turns it into shared infrastructure — authentication, versioning, and monitoring to maintain — so self-host when team-wide sharing is worth that cost. ### Custom MCP servers Build your own MCP server when existing integrations do not match your workflow or when the useful capability sits behind internal systems. With the official TypeScript SDK, a small server that exposes one tool and one prompt looks like this. It runs as a child process of the client and talks over standard input/output — the stdio transport: ```ts deploy-server theme={null} import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import { z } from 'zod'; const server = new McpServer({ name: 'deploy-server', version: '1.0.0' }); server.registerTool( 'search_recent_deploy_errors', { title: 'Search recent deploy errors', description: 'Searches deploy logs for errors in the given service and time range. ' + 'Use when investigating a failed or unstable deployment.', inputSchema: { service: z.string().describe('Service name (e.g. "api-gateway")'), hours: z.number().max(72).default(24).describe('Hours to look back'), }, }, async ({ service, hours }) => { const errors = await fetchDeployErrors(service, hours); const lines = [ `### Deploy errors: ${service} (last ${hours}h)`, `total: ${errors.length}`, ...errors.map((e) => `- ${e.occurredAt} ${e.summary}`), ]; return { content: [{ type: 'text', text: lines.join('\n') }] }; } ); server.registerPrompt( 'investigate_deploy_failure', { description: 'Investigate a failed deployment step by step', argsSchema: { service: z.string().describe('Service name to investigate'), }, }, async ({ service }) => ({ messages: [ { role: 'user', content: { type: 'text', text: [ 'Investigate the failed deployment in the following order.', `1. Call \`search_recent_deploy_errors\` with service "${service}".`, '2. Call `get_deploy_status` and find the release that introduced the errors.', '3. Summarize the likely causes and propose a rollback decision.', ].join('\n'), }, }, ], }) ); await server.connect(new StdioServerTransport()); ``` In use, the user never names the tool. When someone asks "did yesterday's api-gateway deploy throw any errors?", the agent matches the request against the tool's description, calls it with `{ service: "api-gateway", hours: 24 }`, and answers from the returned summary. The prompt is invoked explicitly instead: the user picks `investigate_deploy_failure` from the client's prompt list, the expanded text becomes the agent's instruction, and the agent walks the steps — calling the server's tools in order — the same way every time. The client launches the server by command: ```json client configuration theme={null} { "mcpServers": { "deploy-server": { "command": "node", "args": ["./dist/deploy-server.js"] } } } ``` Start narrow: one or two well-defined tools are better than a broad wrapper over an entire API. Design the surface from the agent's point of view — expose only the inputs the agent needs for the task it is allowed to perform — and when a tool mutates state, make the operation explicit in the name and result. Above all, the description is the heart of MCP server design. The agent picks a tool by matching the natural-language request against its description, so how the description is written decides whether the tool gets used. It is easy to neglect in a quick prototype, and worth writing carefully first. When a custom server later needs to be shared, the same code serves remotely by switching the transport from stdio to Streamable HTTP. ## Operational considerations MCP gives agents data access and code execution paths, so operating it well is mostly about managing trust and scope: which servers to connect, who can use what, how much context comes back, and how many choices the agent has at once. ### Server trust Connecting an MCP server hands it a path into the agent's context and actions, so the first operational decision is which servers to trust. The MCP specification treats tool descriptions as untrusted unless they come from a trusted server: a description can carry instructions, and the agent reads them as part of deciding what to call. This is one instance of the general problem covered in [Security](/ai/security), which is where the risk and the defenses against it are described. * Connect servers from providers you already trust, and prefer official ones. * Review what a server exposes — its tools and their descriptions — before rolling it out to a team. * Reassess after updates: a server's tool set can change over time. ### Authentication and permissions Treat an MCP server as an application integration, not as a side channel. Authentication should identify the user, workspace, service account, or environment clearly enough for policy and audit. The MCP specification puts user consent at the center: the host obtains explicit approval before a tool runs, and the user stays in control of what data is shared. Prefer least privilege: * Give read-only access by default. * Split read tools from write tools. * Scope tokens to the smallest useful set of systems and operations. * Require confirmation for destructive, expensive, or externally visible actions. * Log the request metadata needed for debugging and audit. Authorization belongs on both sides. The server should enforce what the backing system allows, and the client should decide which exposed capabilities the agent may use in a given session. How to design the client-side half — allowlists, read-only roles, and which actions to gate behind human approval — is covered in [Security](/ai/security). ### Context efficiency An MCP integration can make context better or worse. It helps when the server returns the exact data needed for the task. It hurts when every call returns a large raw object that the agent then has to carry. Design for small, decision-ready responses: * Return summaries before full bodies. * Provide pagination, filters, and stable identifiers. * Let the agent fetch detail after it selects a candidate. * Omit fields that are not useful for the task. * Prefer structured data over prose when the next step is mechanical. This is the same context-management discipline used in agentic workflows: keep bulky raw data outside the main context and move in only what decisions require. ### Tool count management More tools do not automatically make an agent more capable. Every tool definition consumes the agent's context by itself, and too many overlapping tools increase selection errors, slow the agent down, and make permission review harder. Keep the tool set small and legible: * Merge tools that are always used together. * Split tools that have different risk levels. * Use clear names that describe the action and scope. * Hide experimental tools from default sessions. * Remove tools that are no longer used. Tool descriptions matter because the agent uses them to decide what to call. Describe the tool's purpose, required inputs, and important limits. If two tools' descriptions look like they serve the same purpose, the agent cannot tell which one to call and will pick one arbitrarily. MCP is the integration layer. The surrounding work still needs clear task boundaries, repository conventions, and human verification. See [Agentic Workflow](/ai/agentic-workflow) for delegation design and [Vibe Coding](/ai/vibe-coding) for collaborative coding practice. ## Related pages Design the delegation model around agents that plan, implement, and verify work with clear human responsibility. Package repeatable procedures and supporting files that an agent loads only when they become relevant. Why untrusted tool responses are dangerous, and how to bound what an agent may do with what it reads. Bundle commands, agents, skills, hooks, and MCP configuration into one unit a team can install and update together.