0Pricing
Claude Architect · 课时

工具、资源与提示词

MCP 服务器可以公开的三种基本原语。

工具、资源与提示词 是 CoddyKit 上的免费 Claude Architect 课时。 这是第 1 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Claude Architect 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Claude Architect 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Three Primitives, One Server

The Model Context Protocol (MCP) lets an external server expose capabilities to Claude through a standard interface. A single server can offer exactly three kinds of primitives:

  • Tools — actions the model can invoke (do something, often with side effects)
  • Resources — read-only data and context the model can pull in (schemas, catalogs, docs)
  • Prompts — reusable templates that shape how a task is asked

Knowing which primitive fits a capability is a core architect skill: misclassifying an action as a resource (or vice-versa) leads to brittle, confusing integrations.

Tools — Actions With Effects

Tools are actions. They are the primitive the model calls to make something happen: query a live database, create a ticket, send a message, process a refund. Tools are the MCP analog of the Agent SDK tools you already define in an API request's tools field.

Because tools drive behavior, their descriptions are the primary selection mechanism — not their names. A good tool description states purpose, return values, input formats with examples, and applicability boundaries so the model routes to the right tool.

# An MCP server exposing a Tool (action) — Python style
@mcp.tool()
def lookup_order(order_id: str) -> dict:
    """Fetch a single order by its ID from the orders DB.

    Input: order_id as 'ORD-12345' (string, required).
    Returns: {status, total_cents, items[]}.
    Use only when you already have an exact order ID;
    for fuzzy search use search_orders instead.
    """
    return db.fetch_order(order_id)

Resources — Read-Only Context

Resources are read-only data. They give the model context to reason over rather than an action to perform: a database schema, a product catalog, an API spec, a config file, a reference document.

The mental test: if the model is reading to understand, it is a Resource; if the model is doing to change something, it is a Tool. Exposing a stable schema as a Resource avoids spending a tool call (and a round-trip) just to fetch context the model needs up front.

# An MCP Resource — read-only context the model can load
@mcp.resource("schema://orders")
def orders_schema() -> str:
    """The current orders table schema (read-only).
    Provides column names and types so the model can
    write correct queries without guessing.
    """
    return read_file("db/orders.schema.sql")

Prompts — Reusable Templates

Prompts are templates. An MCP server can publish parameterized, reusable prompt templates — for example a standard "summarize this incident" or "review this PR for security issues" prompt that bakes in the team's preferred structure and criteria.

Prompts are not actions and not data; they are how a task is asked. They let a server ship best-practice instructions (explicit criteria, few-shot examples) so every consumer phrases the request consistently instead of reinventing it.

# An MCP Prompt — a reusable, parameterized template
@mcp.prompt()
def review_pr(diff: str, focus: str = "security") -> str:
    return (
        "Review the following diff. "
        f"Flag a finding only when it clearly violates {focus} "
        "best practice; do not flag style preferences.\n\n"
        f"{diff}"
    )

The Decision: Tool vs Resource vs Prompt

Put the three side by side and the boundaries get sharp:

  • Tool — "Do X." Has effects, may fail transiently, is invoked mid-loop. e.g. process_refund.
  • Resource — "Here is X to read." Stable, idempotent, no side effects. e.g. the orders schema.
  • Prompt — "Ask it like this." A template, not a call. e.g. the PR-review template.

A frequent mistake is wrapping read-only context as a tool. That works, but it costs a tool call and a round-trip; a Resource delivers the same context more cheaply and signals intent clearly.

Configuring an MCP Server: Scope

Where you register a server controls who gets it. Two scopes matter:

  • Project scope — .mcp.json at the repo root, committed to version control. Shared with the whole team; everyone who clones the repo gets the same servers.
  • User scope — ~/.claude.json, personal and NOT shared via VCS. Good for your own credentials or experimental servers.

For an integration the whole team relies on, choose project scope so it lives in VCS and new teammates inherit it automatically.

{
  "mcpServers": {
    "orders": {
      "command": "node",
      "args": ["./servers/orders-mcp.js"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Secrets: Never Commit Tokens

Because project-scope .mcp.json is committed to VCS, you must never hard-code secrets in it. Reference them through environment variables instead — for example ${GITHUB_TOKEN} — so the config is shareable while the actual token stays out of source control.

This is a security guarantee, not a convenience: a committed token is a leaked token. Env-var indirection keeps the project config portable and the credential private to each machine.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

Prefer Community Servers

For standard integrations — GitHub, Postgres, Slack, filesystem — prefer a well-maintained community MCP server over building a custom one. You inherit battle-tested tool descriptions, error handling, and updates for free.

Reserve a custom server for genuinely proprietary systems where no community option exists. This mirrors a broader architect principle: don't rebuild standard plumbing; spend your effort on what is actually unique to your domain.

Structured Errors From Tools

When an MCP tool fails, a generic message like "Operation failed" leaves the model blind — it cannot tell whether to retry, escalate, or try an alternative. Always return structured errors so the model can route intelligently.

A good MCP error carries: isError: true, an errorCategory (transient / validation / business / permission), an isRetryable flag, a human message, the attempted_query, and any partial_results. The category and retryable flag are what turn a dead end into an intelligent recovery.

{
  "isError": true,
  "errorCategory": "transient",
  "isRetryable": true,
  "message": "DB connection timed out after 5s",
  "attempted_query": "SELECT * FROM orders WHERE id='ORD-1'",
  "partial_results": []
}

Tool Hygiene Carries Into MCP

Everything you know about good tool design applies to MCP tools too:

  • Descriptions, not names, drive selection — write purpose, returns, input formats, edge cases, and boundaries.
  • Scope tools to the role. About 4-5 tools per agent is optimal; once you approach 18+, selection reliability degrades.
  • Avoid overlap. Two tools with ambiguous, similar descriptions cause misrouting.

An MCP server that dumps 20 vaguely-described tools on an agent is an anti-pattern, no matter how capable each tool is.

Putting It Together

Picture an orders MCP server for a support agent. A clean design uses all three primitives deliberately:

  • Resource schema://orders — so the agent understands the data model up front, no tool call needed.
  • Tools lookup_order, process_refund — the actions, each with a sharp description and structured errors.
  • Prompt refund_review — a template encoding the team's refund-justification criteria.

Register it in project-scope .mcp.json, pull secrets from env vars, and keep the tool count lean. That is an architect-grade MCP integration.

Quick Check

Test your grasp of the three MCP primitives and how to expose them.

Recap: Tools, Resources & Prompts

Key takeaways for the exam and for real builds:

  • An MCP server exposes three primitives: Tools (actions), Resources (read-only data/context), Prompts (templates).
  • Decide by intent: doing → Tool, reading to understand → Resource, how to ask → Prompt.
  • Scope: project .mcp.json (shared in VCS) vs user ~/.claude.json (personal).
  • Secrets go through env vars like ${GITHUB_TOKEN} — never commit tokens.
  • Prefer community servers for standard integrations; keep tools to ~4-5 with sharp descriptions.
  • Return structured errors (isError, errorCategory, isRetryable, attempted_query, partial_results) so the model can recover intelligently.

常见问题解答

「工具、资源与提示词」课时是免费的吗？

是的 — 「工具、资源与提示词」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Claude Architect 课程的其余内容，请升级到 CoddyKit PRO。 Claude Architect 课程共包含 4 节课。

「工具、资源与提示词」这节课中我会学到什么？

MCP 服务器可以公开的三种基本原语。 你通过在浏览器中直接运行的动手代码来练习 Claude Architect，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Claude Architect 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Claude Architect 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。

「工具、资源与提示词」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Claude Architect 课中编写并运行代码吗？

能。每节 Claude Architect 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. 工具、资源与提示词
  2. 项目范围与用户范围
  3. 使用环境变量管理机密
  4. 社区服务器与自定义服务器
← 返回 Claude Architect