This is page 52 of 52. Use http://codebase.md/eyaltoledano/claude-task-master?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .changeset
│ ├── config.json
│ └── README.md
├── .claude
│ ├── agents
│ │ ├── task-checker.md
│ │ ├── task-executor.md
│ │ └── task-orchestrator.md
│ ├── commands
│ │ ├── dedupe.md
│ │ └── tm
│ │ ├── add-dependency
│ │ │ └── add-dependency.md
│ │ ├── add-subtask
│ │ │ ├── add-subtask.md
│ │ │ └── convert-task-to-subtask.md
│ │ ├── add-task
│ │ │ └── add-task.md
│ │ ├── analyze-complexity
│ │ │ └── analyze-complexity.md
│ │ ├── complexity-report
│ │ │ └── complexity-report.md
│ │ ├── expand
│ │ │ ├── expand-all-tasks.md
│ │ │ └── expand-task.md
│ │ ├── fix-dependencies
│ │ │ └── fix-dependencies.md
│ │ ├── generate
│ │ │ └── generate-tasks.md
│ │ ├── help.md
│ │ ├── init
│ │ │ ├── init-project-quick.md
│ │ │ └── init-project.md
│ │ ├── learn.md
│ │ ├── list
│ │ │ ├── list-tasks-by-status.md
│ │ │ ├── list-tasks-with-subtasks.md
│ │ │ └── list-tasks.md
│ │ ├── models
│ │ │ ├── setup-models.md
│ │ │ └── view-models.md
│ │ ├── next
│ │ │ └── next-task.md
│ │ ├── parse-prd
│ │ │ ├── parse-prd-with-research.md
│ │ │ └── parse-prd.md
│ │ ├── remove-dependency
│ │ │ └── remove-dependency.md
│ │ ├── remove-subtask
│ │ │ └── remove-subtask.md
│ │ ├── remove-subtasks
│ │ │ ├── remove-all-subtasks.md
│ │ │ └── remove-subtasks.md
│ │ ├── remove-task
│ │ │ └── remove-task.md
│ │ ├── set-status
│ │ │ ├── to-cancelled.md
│ │ │ ├── to-deferred.md
│ │ │ ├── to-done.md
│ │ │ ├── to-in-progress.md
│ │ │ ├── to-pending.md
│ │ │ └── to-review.md
│ │ ├── setup
│ │ │ ├── install-taskmaster.md
│ │ │ └── quick-install-taskmaster.md
│ │ ├── show
│ │ │ └── show-task.md
│ │ ├── status
│ │ │ └── project-status.md
│ │ ├── sync-readme
│ │ │ └── sync-readme.md
│ │ ├── tm-main.md
│ │ ├── update
│ │ │ ├── update-single-task.md
│ │ │ ├── update-task.md
│ │ │ └── update-tasks-from-id.md
│ │ ├── utils
│ │ │ └── analyze-project.md
│ │ ├── validate-dependencies
│ │ │ └── validate-dependencies.md
│ │ └── workflows
│ │ ├── auto-implement-tasks.md
│ │ ├── command-pipeline.md
│ │ └── smart-workflow.md
│ └── TM_COMMANDS_GUIDE.md
├── .coderabbit.yaml
├── .cursor
│ ├── mcp.json
│ └── rules
│ ├── ai_providers.mdc
│ ├── ai_services.mdc
│ ├── architecture.mdc
│ ├── changeset.mdc
│ ├── commands.mdc
│ ├── context_gathering.mdc
│ ├── cursor_rules.mdc
│ ├── dependencies.mdc
│ ├── dev_workflow.mdc
│ ├── git_workflow.mdc
│ ├── glossary.mdc
│ ├── mcp.mdc
│ ├── new_features.mdc
│ ├── self_improve.mdc
│ ├── tags.mdc
│ ├── taskmaster.mdc
│ ├── tasks.mdc
│ ├── telemetry.mdc
│ ├── test_workflow.mdc
│ ├── tests.mdc
│ ├── ui.mdc
│ └── utilities.mdc
├── .cursorignore
├── .env.example
├── .github
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── enhancements---feature-requests.md
│ │ └── feedback.md
│ ├── PULL_REQUEST_TEMPLATE
│ │ ├── bugfix.md
│ │ ├── config.yml
│ │ ├── feature.md
│ │ └── integration.md
│ ├── PULL_REQUEST_TEMPLATE.md
│ ├── scripts
│ │ ├── auto-close-duplicates.mjs
│ │ ├── backfill-duplicate-comments.mjs
│ │ ├── check-pre-release-mode.mjs
│ │ ├── parse-metrics.mjs
│ │ ├── release.mjs
│ │ ├── tag-extension.mjs
│ │ └── utils.mjs
│ └── workflows
│ ├── auto-close-duplicates.yml
│ ├── backfill-duplicate-comments.yml
│ ├── ci.yml
│ ├── claude-dedupe-issues.yml
│ ├── claude-docs-trigger.yml
│ ├── claude-docs-updater.yml
│ ├── claude-issue-triage.yml
│ ├── claude.yml
│ ├── extension-ci.yml
│ ├── extension-release.yml
│ ├── log-issue-events.yml
│ ├── pre-release.yml
│ ├── release-check.yml
│ ├── release.yml
│ ├── update-models-md.yml
│ └── weekly-metrics-discord.yml
├── .gitignore
├── .kiro
│ ├── hooks
│ │ ├── tm-code-change-task-tracker.kiro.hook
│ │ ├── tm-complexity-analyzer.kiro.hook
│ │ ├── tm-daily-standup-assistant.kiro.hook
│ │ ├── tm-git-commit-task-linker.kiro.hook
│ │ ├── tm-pr-readiness-checker.kiro.hook
│ │ ├── tm-task-dependency-auto-progression.kiro.hook
│ │ └── tm-test-success-task-completer.kiro.hook
│ ├── settings
│ │ └── mcp.json
│ └── steering
│ ├── dev_workflow.md
│ ├── kiro_rules.md
│ ├── self_improve.md
│ ├── taskmaster_hooks_workflow.md
│ └── taskmaster.md
├── .manypkg.json
├── .mcp.json
├── .npmignore
├── .nvmrc
├── .taskmaster
│ ├── CLAUDE.md
│ ├── config.json
│ ├── docs
│ │ ├── MIGRATION-ROADMAP.md
│ │ ├── prd-tm-start.txt
│ │ ├── prd.txt
│ │ ├── README.md
│ │ ├── research
│ │ │ ├── 2025-06-14_how-can-i-improve-the-scope-up-and-scope-down-comm.md
│ │ │ ├── 2025-06-14_should-i-be-using-any-specific-libraries-for-this.md
│ │ │ ├── 2025-06-14_test-save-functionality.md
│ │ │ ├── 2025-06-14_test-the-fix-for-duplicate-saves-final-test.md
│ │ │ └── 2025-08-01_do-we-need-to-add-new-commands-or-can-we-just-weap.md
│ │ ├── task-template-importing-prd.txt
│ │ ├── test-prd.txt
│ │ └── tm-core-phase-1.txt
│ ├── reports
│ │ ├── task-complexity-report_cc-kiro-hooks.json
│ │ ├── task-complexity-report_test-prd-tag.json
│ │ ├── task-complexity-report_tm-core-phase-1.json
│ │ ├── task-complexity-report.json
│ │ └── tm-core-complexity.json
│ ├── state.json
│ ├── tasks
│ │ ├── task_001_tm-start.txt
│ │ ├── task_002_tm-start.txt
│ │ ├── task_003_tm-start.txt
│ │ ├── task_004_tm-start.txt
│ │ ├── task_007_tm-start.txt
│ │ └── tasks.json
│ └── templates
│ └── example_prd.txt
├── .vscode
│ ├── extensions.json
│ └── settings.json
├── apps
│ ├── cli
│ │ ├── CHANGELOG.md
│ │ ├── package.json
│ │ ├── src
│ │ │ ├── commands
│ │ │ │ ├── auth.command.ts
│ │ │ │ ├── context.command.ts
│ │ │ │ ├── list.command.ts
│ │ │ │ ├── set-status.command.ts
│ │ │ │ ├── show.command.ts
│ │ │ │ └── start.command.ts
│ │ │ ├── index.ts
│ │ │ ├── ui
│ │ │ │ ├── components
│ │ │ │ │ ├── dashboard.component.ts
│ │ │ │ │ ├── header.component.ts
│ │ │ │ │ ├── index.ts
│ │ │ │ │ ├── next-task.component.ts
│ │ │ │ │ ├── suggested-steps.component.ts
│ │ │ │ │ └── task-detail.component.ts
│ │ │ │ └── index.ts
│ │ │ └── utils
│ │ │ ├── auto-update.ts
│ │ │ └── ui.ts
│ │ └── tsconfig.json
│ ├── docs
│ │ ├── archive
│ │ │ ├── ai-client-utils-example.mdx
│ │ │ ├── ai-development-workflow.mdx
│ │ │ ├── command-reference.mdx
│ │ │ ├── configuration.mdx
│ │ │ ├── cursor-setup.mdx
│ │ │ ├── examples.mdx
│ │ │ └── Installation.mdx
│ │ ├── best-practices
│ │ │ ├── advanced-tasks.mdx
│ │ │ ├── configuration-advanced.mdx
│ │ │ └── index.mdx
│ │ ├── capabilities
│ │ │ ├── cli-root-commands.mdx
│ │ │ ├── index.mdx
│ │ │ ├── mcp.mdx
│ │ │ └── task-structure.mdx
│ │ ├── CHANGELOG.md
│ │ ├── docs.json
│ │ ├── favicon.svg
│ │ ├── getting-started
│ │ │ ├── contribute.mdx
│ │ │ ├── faq.mdx
│ │ │ └── quick-start
│ │ │ ├── configuration-quick.mdx
│ │ │ ├── execute-quick.mdx
│ │ │ ├── installation.mdx
│ │ │ ├── moving-forward.mdx
│ │ │ ├── prd-quick.mdx
│ │ │ ├── quick-start.mdx
│ │ │ ├── requirements.mdx
│ │ │ ├── rules-quick.mdx
│ │ │ └── tasks-quick.mdx
│ │ ├── introduction.mdx
│ │ ├── licensing.md
│ │ ├── logo
│ │ │ ├── dark.svg
│ │ │ ├── light.svg
│ │ │ └── task-master-logo.png
│ │ ├── package.json
│ │ ├── README.md
│ │ ├── style.css
│ │ ├── vercel.json
│ │ └── whats-new.mdx
│ └── extension
│ ├── .vscodeignore
│ ├── assets
│ │ ├── banner.png
│ │ ├── icon-dark.svg
│ │ ├── icon-light.svg
│ │ ├── icon.png
│ │ ├── screenshots
│ │ │ ├── kanban-board.png
│ │ │ └── task-details.png
│ │ └── sidebar-icon.svg
│ ├── CHANGELOG.md
│ ├── components.json
│ ├── docs
│ │ ├── extension-CI-setup.md
│ │ └── extension-development-guide.md
│ ├── esbuild.js
│ ├── LICENSE
│ ├── package.json
│ ├── package.mjs
│ ├── package.publish.json
│ ├── README.md
│ ├── src
│ │ ├── components
│ │ │ ├── ConfigView.tsx
│ │ │ ├── constants.ts
│ │ │ ├── TaskDetails
│ │ │ │ ├── AIActionsSection.tsx
│ │ │ │ ├── DetailsSection.tsx
│ │ │ │ ├── PriorityBadge.tsx
│ │ │ │ ├── SubtasksSection.tsx
│ │ │ │ ├── TaskMetadataSidebar.tsx
│ │ │ │ └── useTaskDetails.ts
│ │ │ ├── TaskDetailsView.tsx
│ │ │ ├── TaskMasterLogo.tsx
│ │ │ └── ui
│ │ │ ├── badge.tsx
│ │ │ ├── breadcrumb.tsx
│ │ │ ├── button.tsx
│ │ │ ├── card.tsx
│ │ │ ├── collapsible.tsx
│ │ │ ├── CollapsibleSection.tsx
│ │ │ ├── dropdown-menu.tsx
│ │ │ ├── label.tsx
│ │ │ ├── scroll-area.tsx
│ │ │ ├── separator.tsx
│ │ │ ├── shadcn-io
│ │ │ │ └── kanban
│ │ │ │ └── index.tsx
│ │ │ └── textarea.tsx
│ │ ├── extension.ts
│ │ ├── index.ts
│ │ ├── lib
│ │ │ └── utils.ts
│ │ ├── services
│ │ │ ├── config-service.ts
│ │ │ ├── error-handler.ts
│ │ │ ├── notification-preferences.ts
│ │ │ ├── polling-service.ts
│ │ │ ├── polling-strategies.ts
│ │ │ ├── sidebar-webview-manager.ts
│ │ │ ├── task-repository.ts
│ │ │ ├── terminal-manager.ts
│ │ │ └── webview-manager.ts
│ │ ├── test
│ │ │ └── extension.test.ts
│ │ ├── utils
│ │ │ ├── configManager.ts
│ │ │ ├── connectionManager.ts
│ │ │ ├── errorHandler.ts
│ │ │ ├── event-emitter.ts
│ │ │ ├── logger.ts
│ │ │ ├── mcpClient.ts
│ │ │ ├── notificationPreferences.ts
│ │ │ └── task-master-api
│ │ │ ├── cache
│ │ │ │ └── cache-manager.ts
│ │ │ ├── index.ts
│ │ │ ├── mcp-client.ts
│ │ │ ├── transformers
│ │ │ │ └── task-transformer.ts
│ │ │ └── types
│ │ │ └── index.ts
│ │ └── webview
│ │ ├── App.tsx
│ │ ├── components
│ │ │ ├── AppContent.tsx
│ │ │ ├── EmptyState.tsx
│ │ │ ├── ErrorBoundary.tsx
│ │ │ ├── PollingStatus.tsx
│ │ │ ├── PriorityBadge.tsx
│ │ │ ├── SidebarView.tsx
│ │ │ ├── TagDropdown.tsx
│ │ │ ├── TaskCard.tsx
│ │ │ ├── TaskEditModal.tsx
│ │ │ ├── TaskMasterKanban.tsx
│ │ │ ├── ToastContainer.tsx
│ │ │ └── ToastNotification.tsx
│ │ ├── constants
│ │ │ └── index.ts
│ │ ├── contexts
│ │ │ └── VSCodeContext.tsx
│ │ ├── hooks
│ │ │ ├── useTaskQueries.ts
│ │ │ ├── useVSCodeMessages.ts
│ │ │ └── useWebviewHeight.ts
│ │ ├── index.css
│ │ ├── index.tsx
│ │ ├── providers
│ │ │ └── QueryProvider.tsx
│ │ ├── reducers
│ │ │ └── appReducer.ts
│ │ ├── sidebar.tsx
│ │ ├── types
│ │ │ └── index.ts
│ │ └── utils
│ │ ├── logger.ts
│ │ └── toast.ts
│ └── tsconfig.json
├── assets
│ ├── .windsurfrules
│ ├── AGENTS.md
│ ├── claude
│ │ ├── agents
│ │ │ ├── task-checker.md
│ │ │ ├── task-executor.md
│ │ │ └── task-orchestrator.md
│ │ ├── commands
│ │ │ └── tm
│ │ │ ├── add-dependency
│ │ │ │ └── add-dependency.md
│ │ │ ├── add-subtask
│ │ │ │ ├── add-subtask.md
│ │ │ │ └── convert-task-to-subtask.md
│ │ │ ├── add-task
│ │ │ │ └── add-task.md
│ │ │ ├── analyze-complexity
│ │ │ │ └── analyze-complexity.md
│ │ │ ├── clear-subtasks
│ │ │ │ ├── clear-all-subtasks.md
│ │ │ │ └── clear-subtasks.md
│ │ │ ├── complexity-report
│ │ │ │ └── complexity-report.md
│ │ │ ├── expand
│ │ │ │ ├── expand-all-tasks.md
│ │ │ │ └── expand-task.md
│ │ │ ├── fix-dependencies
│ │ │ │ └── fix-dependencies.md
│ │ │ ├── generate
│ │ │ │ └── generate-tasks.md
│ │ │ ├── help.md
│ │ │ ├── init
│ │ │ │ ├── init-project-quick.md
│ │ │ │ └── init-project.md
│ │ │ ├── learn.md
│ │ │ ├── list
│ │ │ │ ├── list-tasks-by-status.md
│ │ │ │ ├── list-tasks-with-subtasks.md
│ │ │ │ └── list-tasks.md
│ │ │ ├── models
│ │ │ │ ├── setup-models.md
│ │ │ │ └── view-models.md
│ │ │ ├── next
│ │ │ │ └── next-task.md
│ │ │ ├── parse-prd
│ │ │ │ ├── parse-prd-with-research.md
│ │ │ │ └── parse-prd.md
│ │ │ ├── remove-dependency
│ │ │ │ └── remove-dependency.md
│ │ │ ├── remove-subtask
│ │ │ │ └── remove-subtask.md
│ │ │ ├── remove-subtasks
│ │ │ │ ├── remove-all-subtasks.md
│ │ │ │ └── remove-subtasks.md
│ │ │ ├── remove-task
│ │ │ │ └── remove-task.md
│ │ │ ├── set-status
│ │ │ │ ├── to-cancelled.md
│ │ │ │ ├── to-deferred.md
│ │ │ │ ├── to-done.md
│ │ │ │ ├── to-in-progress.md
│ │ │ │ ├── to-pending.md
│ │ │ │ └── to-review.md
│ │ │ ├── setup
│ │ │ │ ├── install-taskmaster.md
│ │ │ │ └── quick-install-taskmaster.md
│ │ │ ├── show
│ │ │ │ └── show-task.md
│ │ │ ├── status
│ │ │ │ └── project-status.md
│ │ │ ├── sync-readme
│ │ │ │ └── sync-readme.md
│ │ │ ├── tm-main.md
│ │ │ ├── update
│ │ │ │ ├── update-single-task.md
│ │ │ │ ├── update-task.md
│ │ │ │ └── update-tasks-from-id.md
│ │ │ ├── utils
│ │ │ │ └── analyze-project.md
│ │ │ ├── validate-dependencies
│ │ │ │ └── validate-dependencies.md
│ │ │ └── workflows
│ │ │ ├── auto-implement-tasks.md
│ │ │ ├── command-pipeline.md
│ │ │ └── smart-workflow.md
│ │ └── TM_COMMANDS_GUIDE.md
│ ├── config.json
│ ├── env.example
│ ├── example_prd.txt
│ ├── gitignore
│ ├── kiro-hooks
│ │ ├── tm-code-change-task-tracker.kiro.hook
│ │ ├── tm-complexity-analyzer.kiro.hook
│ │ ├── tm-daily-standup-assistant.kiro.hook
│ │ ├── tm-git-commit-task-linker.kiro.hook
│ │ ├── tm-pr-readiness-checker.kiro.hook
│ │ ├── tm-task-dependency-auto-progression.kiro.hook
│ │ └── tm-test-success-task-completer.kiro.hook
│ ├── roocode
│ │ ├── .roo
│ │ │ ├── rules-architect
│ │ │ │ └── architect-rules
│ │ │ ├── rules-ask
│ │ │ │ └── ask-rules
│ │ │ ├── rules-code
│ │ │ │ └── code-rules
│ │ │ ├── rules-debug
│ │ │ │ └── debug-rules
│ │ │ ├── rules-orchestrator
│ │ │ │ └── orchestrator-rules
│ │ │ └── rules-test
│ │ │ └── test-rules
│ │ └── .roomodes
│ ├── rules
│ │ ├── cursor_rules.mdc
│ │ ├── dev_workflow.mdc
│ │ ├── self_improve.mdc
│ │ ├── taskmaster_hooks_workflow.mdc
│ │ └── taskmaster.mdc
│ └── scripts_README.md
├── bin
│ └── task-master.js
├── biome.json
├── CHANGELOG.md
├── CLAUDE.md
├── context
│ ├── chats
│ │ ├── add-task-dependencies-1.md
│ │ └── max-min-tokens.txt.md
│ ├── fastmcp-core.txt
│ ├── fastmcp-docs.txt
│ ├── MCP_INTEGRATION.md
│ ├── mcp-js-sdk-docs.txt
│ ├── mcp-protocol-repo.txt
│ ├── mcp-protocol-schema-03262025.json
│ └── mcp-protocol-spec.txt
├── CONTRIBUTING.md
├── docs
│ ├── CLI-COMMANDER-PATTERN.md
│ ├── command-reference.md
│ ├── configuration.md
│ ├── contributor-docs
│ │ └── testing-roo-integration.md
│ ├── cross-tag-task-movement.md
│ ├── examples
│ │ └── claude-code-usage.md
│ ├── examples.md
│ ├── licensing.md
│ ├── mcp-provider-guide.md
│ ├── mcp-provider.md
│ ├── migration-guide.md
│ ├── models.md
│ ├── providers
│ │ └── gemini-cli.md
│ ├── README.md
│ ├── scripts
│ │ └── models-json-to-markdown.js
│ ├── task-structure.md
│ └── tutorial.md
├── images
│ └── logo.png
├── index.js
├── jest.config.js
├── jest.resolver.cjs
├── LICENSE
├── llms-install.md
├── mcp-server
│ ├── server.js
│ └── src
│ ├── core
│ │ ├── __tests__
│ │ │ └── context-manager.test.js
│ │ ├── context-manager.js
│ │ ├── direct-functions
│ │ │ ├── add-dependency.js
│ │ │ ├── add-subtask.js
│ │ │ ├── add-tag.js
│ │ │ ├── add-task.js
│ │ │ ├── analyze-task-complexity.js
│ │ │ ├── cache-stats.js
│ │ │ ├── clear-subtasks.js
│ │ │ ├── complexity-report.js
│ │ │ ├── copy-tag.js
│ │ │ ├── create-tag-from-branch.js
│ │ │ ├── delete-tag.js
│ │ │ ├── expand-all-tasks.js
│ │ │ ├── expand-task.js
│ │ │ ├── fix-dependencies.js
│ │ │ ├── generate-task-files.js
│ │ │ ├── initialize-project.js
│ │ │ ├── list-tags.js
│ │ │ ├── list-tasks.js
│ │ │ ├── models.js
│ │ │ ├── move-task-cross-tag.js
│ │ │ ├── move-task.js
│ │ │ ├── next-task.js
│ │ │ ├── parse-prd.js
│ │ │ ├── remove-dependency.js
│ │ │ ├── remove-subtask.js
│ │ │ ├── remove-task.js
│ │ │ ├── rename-tag.js
│ │ │ ├── research.js
│ │ │ ├── response-language.js
│ │ │ ├── rules.js
│ │ │ ├── scope-down.js
│ │ │ ├── scope-up.js
│ │ │ ├── set-task-status.js
│ │ │ ├── show-task.js
│ │ │ ├── update-subtask-by-id.js
│ │ │ ├── update-task-by-id.js
│ │ │ ├── update-tasks.js
│ │ │ ├── use-tag.js
│ │ │ └── validate-dependencies.js
│ │ ├── task-master-core.js
│ │ └── utils
│ │ ├── env-utils.js
│ │ └── path-utils.js
│ ├── custom-sdk
│ │ ├── errors.js
│ │ ├── index.js
│ │ ├── json-extractor.js
│ │ ├── language-model.js
│ │ ├── message-converter.js
│ │ └── schema-converter.js
│ ├── index.js
│ ├── logger.js
│ ├── providers
│ │ └── mcp-provider.js
│ └── tools
│ ├── add-dependency.js
│ ├── add-subtask.js
│ ├── add-tag.js
│ ├── add-task.js
│ ├── analyze.js
│ ├── clear-subtasks.js
│ ├── complexity-report.js
│ ├── copy-tag.js
│ ├── delete-tag.js
│ ├── expand-all.js
│ ├── expand-task.js
│ ├── fix-dependencies.js
│ ├── generate.js
│ ├── get-operation-status.js
│ ├── get-task.js
│ ├── get-tasks.js
│ ├── index.js
│ ├── initialize-project.js
│ ├── list-tags.js
│ ├── models.js
│ ├── move-task.js
│ ├── next-task.js
│ ├── parse-prd.js
│ ├── remove-dependency.js
│ ├── remove-subtask.js
│ ├── remove-task.js
│ ├── rename-tag.js
│ ├── research.js
│ ├── response-language.js
│ ├── rules.js
│ ├── scope-down.js
│ ├── scope-up.js
│ ├── set-task-status.js
│ ├── update-subtask.js
│ ├── update-task.js
│ ├── update.js
│ ├── use-tag.js
│ ├── utils.js
│ └── validate-dependencies.js
├── mcp-test.js
├── output.json
├── package-lock.json
├── package.json
├── packages
│ ├── build-config
│ │ ├── CHANGELOG.md
│ │ ├── package.json
│ │ ├── src
│ │ │ └── tsdown.base.ts
│ │ └── tsconfig.json
│ └── tm-core
│ ├── .gitignore
│ ├── CHANGELOG.md
│ ├── docs
│ │ └── listTasks-architecture.md
│ ├── package.json
│ ├── POC-STATUS.md
│ ├── README.md
│ ├── src
│ │ ├── auth
│ │ │ ├── auth-manager.test.ts
│ │ │ ├── auth-manager.ts
│ │ │ ├── config.ts
│ │ │ ├── credential-store.test.ts
│ │ │ ├── credential-store.ts
│ │ │ ├── index.ts
│ │ │ ├── oauth-service.ts
│ │ │ ├── supabase-session-storage.ts
│ │ │ └── types.ts
│ │ ├── clients
│ │ │ ├── index.ts
│ │ │ └── supabase-client.ts
│ │ ├── config
│ │ │ ├── config-manager.spec.ts
│ │ │ ├── config-manager.ts
│ │ │ ├── index.ts
│ │ │ └── services
│ │ │ ├── config-loader.service.spec.ts
│ │ │ ├── config-loader.service.ts
│ │ │ ├── config-merger.service.spec.ts
│ │ │ ├── config-merger.service.ts
│ │ │ ├── config-persistence.service.spec.ts
│ │ │ ├── config-persistence.service.ts
│ │ │ ├── environment-config-provider.service.spec.ts
│ │ │ ├── environment-config-provider.service.ts
│ │ │ ├── index.ts
│ │ │ ├── runtime-state-manager.service.spec.ts
│ │ │ └── runtime-state-manager.service.ts
│ │ ├── constants
│ │ │ └── index.ts
│ │ ├── entities
│ │ │ └── task.entity.ts
│ │ ├── errors
│ │ │ ├── index.ts
│ │ │ └── task-master-error.ts
│ │ ├── executors
│ │ │ ├── base-executor.ts
│ │ │ ├── claude-executor.ts
│ │ │ ├── executor-factory.ts
│ │ │ ├── executor-service.ts
│ │ │ ├── index.ts
│ │ │ └── types.ts
│ │ ├── index.ts
│ │ ├── interfaces
│ │ │ ├── ai-provider.interface.ts
│ │ │ ├── configuration.interface.ts
│ │ │ ├── index.ts
│ │ │ └── storage.interface.ts
│ │ ├── logger
│ │ │ ├── factory.ts
│ │ │ ├── index.ts
│ │ │ └── logger.ts
│ │ ├── mappers
│ │ │ └── TaskMapper.ts
│ │ ├── parser
│ │ │ └── index.ts
│ │ ├── providers
│ │ │ ├── ai
│ │ │ │ ├── base-provider.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ ├── repositories
│ │ │ ├── supabase-task-repository.ts
│ │ │ └── task-repository.interface.ts
│ │ ├── services
│ │ │ ├── index.ts
│ │ │ ├── organization.service.ts
│ │ │ ├── task-execution-service.ts
│ │ │ └── task-service.ts
│ │ ├── storage
│ │ │ ├── api-storage.ts
│ │ │ ├── file-storage
│ │ │ │ ├── file-operations.ts
│ │ │ │ ├── file-storage.ts
│ │ │ │ ├── format-handler.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── path-resolver.ts
│ │ │ ├── index.ts
│ │ │ └── storage-factory.ts
│ │ ├── subpath-exports.test.ts
│ │ ├── task-master-core.ts
│ │ ├── types
│ │ │ ├── database.types.ts
│ │ │ ├── index.ts
│ │ │ └── legacy.ts
│ │ └── utils
│ │ ├── id-generator.ts
│ │ └── index.ts
│ ├── tests
│ │ ├── integration
│ │ │ └── list-tasks.test.ts
│ │ ├── mocks
│ │ │ └── mock-provider.ts
│ │ ├── setup.ts
│ │ └── unit
│ │ ├── base-provider.test.ts
│ │ ├── executor.test.ts
│ │ └── smoke.test.ts
│ ├── tsconfig.json
│ └── vitest.config.ts
├── README-task-master.md
├── README.md
├── scripts
│ ├── dev.js
│ ├── init.js
│ ├── modules
│ │ ├── ai-services-unified.js
│ │ ├── commands.js
│ │ ├── config-manager.js
│ │ ├── dependency-manager.js
│ │ ├── index.js
│ │ ├── prompt-manager.js
│ │ ├── supported-models.json
│ │ ├── sync-readme.js
│ │ ├── task-manager
│ │ │ ├── add-subtask.js
│ │ │ ├── add-task.js
│ │ │ ├── analyze-task-complexity.js
│ │ │ ├── clear-subtasks.js
│ │ │ ├── expand-all-tasks.js
│ │ │ ├── expand-task.js
│ │ │ ├── find-next-task.js
│ │ │ ├── generate-task-files.js
│ │ │ ├── is-task-dependent.js
│ │ │ ├── list-tasks.js
│ │ │ ├── migrate.js
│ │ │ ├── models.js
│ │ │ ├── move-task.js
│ │ │ ├── parse-prd
│ │ │ │ ├── index.js
│ │ │ │ ├── parse-prd-config.js
│ │ │ │ ├── parse-prd-helpers.js
│ │ │ │ ├── parse-prd-non-streaming.js
│ │ │ │ ├── parse-prd-streaming.js
│ │ │ │ └── parse-prd.js
│ │ │ ├── remove-subtask.js
│ │ │ ├── remove-task.js
│ │ │ ├── research.js
│ │ │ ├── response-language.js
│ │ │ ├── scope-adjustment.js
│ │ │ ├── set-task-status.js
│ │ │ ├── tag-management.js
│ │ │ ├── task-exists.js
│ │ │ ├── update-single-task-status.js
│ │ │ ├── update-subtask-by-id.js
│ │ │ ├── update-task-by-id.js
│ │ │ └── update-tasks.js
│ │ ├── task-manager.js
│ │ ├── ui.js
│ │ ├── update-config-tokens.js
│ │ ├── utils
│ │ │ ├── contextGatherer.js
│ │ │ ├── fuzzyTaskSearch.js
│ │ │ └── git-utils.js
│ │ └── utils.js
│ ├── task-complexity-report.json
│ ├── test-claude-errors.js
│ └── test-claude.js
├── src
│ ├── ai-providers
│ │ ├── anthropic.js
│ │ ├── azure.js
│ │ ├── base-provider.js
│ │ ├── bedrock.js
│ │ ├── claude-code.js
│ │ ├── custom-sdk
│ │ │ ├── claude-code
│ │ │ │ ├── errors.js
│ │ │ │ ├── index.js
│ │ │ │ ├── json-extractor.js
│ │ │ │ ├── language-model.js
│ │ │ │ ├── message-converter.js
│ │ │ │ └── types.js
│ │ │ └── grok-cli
│ │ │ ├── errors.js
│ │ │ ├── index.js
│ │ │ ├── json-extractor.js
│ │ │ ├── language-model.js
│ │ │ ├── message-converter.js
│ │ │ └── types.js
│ │ ├── gemini-cli.js
│ │ ├── google-vertex.js
│ │ ├── google.js
│ │ ├── grok-cli.js
│ │ ├── groq.js
│ │ ├── index.js
│ │ ├── ollama.js
│ │ ├── openai.js
│ │ ├── openrouter.js
│ │ ├── perplexity.js
│ │ └── xai.js
│ ├── constants
│ │ ├── commands.js
│ │ ├── paths.js
│ │ ├── profiles.js
│ │ ├── providers.js
│ │ ├── rules-actions.js
│ │ ├── task-priority.js
│ │ └── task-status.js
│ ├── profiles
│ │ ├── amp.js
│ │ ├── base-profile.js
│ │ ├── claude.js
│ │ ├── cline.js
│ │ ├── codex.js
│ │ ├── cursor.js
│ │ ├── gemini.js
│ │ ├── index.js
│ │ ├── kilo.js
│ │ ├── kiro.js
│ │ ├── opencode.js
│ │ ├── roo.js
│ │ ├── trae.js
│ │ ├── vscode.js
│ │ ├── windsurf.js
│ │ └── zed.js
│ ├── progress
│ │ ├── base-progress-tracker.js
│ │ ├── cli-progress-factory.js
│ │ ├── parse-prd-tracker.js
│ │ ├── progress-tracker-builder.js
│ │ └── tracker-ui.js
│ ├── prompts
│ │ ├── add-task.json
│ │ ├── analyze-complexity.json
│ │ ├── expand-task.json
│ │ ├── parse-prd.json
│ │ ├── README.md
│ │ ├── research.json
│ │ ├── schemas
│ │ │ ├── parameter.schema.json
│ │ │ ├── prompt-template.schema.json
│ │ │ ├── README.md
│ │ │ └── variant.schema.json
│ │ ├── update-subtask.json
│ │ ├── update-task.json
│ │ └── update-tasks.json
│ ├── provider-registry
│ │ └── index.js
│ ├── task-master.js
│ ├── ui
│ │ ├── confirm.js
│ │ ├── indicators.js
│ │ └── parse-prd.js
│ └── utils
│ ├── asset-resolver.js
│ ├── create-mcp-config.js
│ ├── format.js
│ ├── getVersion.js
│ ├── logger-utils.js
│ ├── manage-gitignore.js
│ ├── path-utils.js
│ ├── profiles.js
│ ├── rule-transformer.js
│ ├── stream-parser.js
│ └── timeout-manager.js
├── test-clean-tags.js
├── test-config-manager.js
├── test-prd.txt
├── test-tag-functions.js
├── test-version-check-full.js
├── test-version-check.js
├── tests
│ ├── e2e
│ │ ├── e2e_helpers.sh
│ │ ├── parse_llm_output.cjs
│ │ ├── run_e2e.sh
│ │ ├── run_fallback_verification.sh
│ │ └── test_llm_analysis.sh
│ ├── fixture
│ │ └── test-tasks.json
│ ├── fixtures
│ │ ├── .taskmasterconfig
│ │ ├── sample-claude-response.js
│ │ ├── sample-prd.txt
│ │ └── sample-tasks.js
│ ├── integration
│ │ ├── claude-code-optional.test.js
│ │ ├── cli
│ │ │ ├── commands.test.js
│ │ │ ├── complex-cross-tag-scenarios.test.js
│ │ │ └── move-cross-tag.test.js
│ │ ├── manage-gitignore.test.js
│ │ ├── mcp-server
│ │ │ └── direct-functions.test.js
│ │ ├── move-task-cross-tag.integration.test.js
│ │ ├── move-task-simple.integration.test.js
│ │ └── profiles
│ │ ├── amp-init-functionality.test.js
│ │ ├── claude-init-functionality.test.js
│ │ ├── cline-init-functionality.test.js
│ │ ├── codex-init-functionality.test.js
│ │ ├── cursor-init-functionality.test.js
│ │ ├── gemini-init-functionality.test.js
│ │ ├── opencode-init-functionality.test.js
│ │ ├── roo-files-inclusion.test.js
│ │ ├── roo-init-functionality.test.js
│ │ ├── rules-files-inclusion.test.js
│ │ ├── trae-init-functionality.test.js
│ │ ├── vscode-init-functionality.test.js
│ │ └── windsurf-init-functionality.test.js
│ ├── manual
│ │ ├── progress
│ │ │ ├── parse-prd-analysis.js
│ │ │ ├── test-parse-prd.js
│ │ │ └── TESTING_GUIDE.md
│ │ └── prompts
│ │ ├── prompt-test.js
│ │ └── README.md
│ ├── README.md
│ ├── setup.js
│ └── unit
│ ├── ai-providers
│ │ ├── claude-code.test.js
│ │ ├── custom-sdk
│ │ │ └── claude-code
│ │ │ └── language-model.test.js
│ │ ├── gemini-cli.test.js
│ │ ├── mcp-components.test.js
│ │ └── openai.test.js
│ ├── ai-services-unified.test.js
│ ├── commands.test.js
│ ├── config-manager.test.js
│ ├── config-manager.test.mjs
│ ├── dependency-manager.test.js
│ ├── init.test.js
│ ├── initialize-project.test.js
│ ├── kebab-case-validation.test.js
│ ├── manage-gitignore.test.js
│ ├── mcp
│ │ └── tools
│ │ ├── __mocks__
│ │ │ └── move-task.js
│ │ ├── add-task.test.js
│ │ ├── analyze-complexity.test.js
│ │ ├── expand-all.test.js
│ │ ├── get-tasks.test.js
│ │ ├── initialize-project.test.js
│ │ ├── move-task-cross-tag-options.test.js
│ │ ├── move-task-cross-tag.test.js
│ │ └── remove-task.test.js
│ ├── mcp-providers
│ │ ├── mcp-components.test.js
│ │ └── mcp-provider.test.js
│ ├── parse-prd.test.js
│ ├── profiles
│ │ ├── amp-integration.test.js
│ │ ├── claude-integration.test.js
│ │ ├── cline-integration.test.js
│ │ ├── codex-integration.test.js
│ │ ├── cursor-integration.test.js
│ │ ├── gemini-integration.test.js
│ │ ├── kilo-integration.test.js
│ │ ├── kiro-integration.test.js
│ │ ├── mcp-config-validation.test.js
│ │ ├── opencode-integration.test.js
│ │ ├── profile-safety-check.test.js
│ │ ├── roo-integration.test.js
│ │ ├── rule-transformer-cline.test.js
│ │ ├── rule-transformer-cursor.test.js
│ │ ├── rule-transformer-gemini.test.js
│ │ ├── rule-transformer-kilo.test.js
│ │ ├── rule-transformer-kiro.test.js
│ │ ├── rule-transformer-opencode.test.js
│ │ ├── rule-transformer-roo.test.js
│ │ ├── rule-transformer-trae.test.js
│ │ ├── rule-transformer-vscode.test.js
│ │ ├── rule-transformer-windsurf.test.js
│ │ ├── rule-transformer-zed.test.js
│ │ ├── rule-transformer.test.js
│ │ ├── selective-profile-removal.test.js
│ │ ├── subdirectory-support.test.js
│ │ ├── trae-integration.test.js
│ │ ├── vscode-integration.test.js
│ │ ├── windsurf-integration.test.js
│ │ └── zed-integration.test.js
│ ├── progress
│ │ └── base-progress-tracker.test.js
│ ├── prompt-manager.test.js
│ ├── prompts
│ │ └── expand-task-prompt.test.js
│ ├── providers
│ │ └── provider-registry.test.js
│ ├── scripts
│ │ └── modules
│ │ ├── commands
│ │ │ ├── move-cross-tag.test.js
│ │ │ └── README.md
│ │ ├── dependency-manager
│ │ │ ├── circular-dependencies.test.js
│ │ │ ├── cross-tag-dependencies.test.js
│ │ │ └── fix-dependencies-command.test.js
│ │ ├── task-manager
│ │ │ ├── add-subtask.test.js
│ │ │ ├── add-task.test.js
│ │ │ ├── analyze-task-complexity.test.js
│ │ │ ├── clear-subtasks.test.js
│ │ │ ├── complexity-report-tag-isolation.test.js
│ │ │ ├── expand-all-tasks.test.js
│ │ │ ├── expand-task.test.js
│ │ │ ├── find-next-task.test.js
│ │ │ ├── generate-task-files.test.js
│ │ │ ├── list-tasks.test.js
│ │ │ ├── move-task-cross-tag.test.js
│ │ │ ├── move-task.test.js
│ │ │ ├── parse-prd.test.js
│ │ │ ├── remove-subtask.test.js
│ │ │ ├── remove-task.test.js
│ │ │ ├── research.test.js
│ │ │ ├── scope-adjustment.test.js
│ │ │ ├── set-task-status.test.js
│ │ │ ├── setup.js
│ │ │ ├── update-single-task-status.test.js
│ │ │ ├── update-subtask-by-id.test.js
│ │ │ ├── update-task-by-id.test.js
│ │ │ └── update-tasks.test.js
│ │ ├── ui
│ │ │ └── cross-tag-error-display.test.js
│ │ └── utils-tag-aware-paths.test.js
│ ├── task-finder.test.js
│ ├── task-manager
│ │ ├── clear-subtasks.test.js
│ │ ├── move-task.test.js
│ │ ├── tag-boundary.test.js
│ │ └── tag-management.test.js
│ ├── task-master.test.js
│ ├── ui
│ │ └── indicators.test.js
│ ├── ui.test.js
│ ├── utils-strip-ansi.test.js
│ └── utils.test.js
├── tsconfig.json
├── tsdown.config.ts
└── turbo.json
```
# Files
--------------------------------------------------------------------------------
/context/mcp-protocol-repo.txt:
--------------------------------------------------------------------------------
```
1 | # Example Clients
2 | Source: https://modelcontextprotocol.io/clients
3 |
4 | A list of applications that support MCP integrations
5 |
6 | This page provides an overview of applications that support the Model Context Protocol (MCP). Each client may support different MCP features, allowing for varying levels of integration with MCP servers.
7 |
8 | ## Feature support matrix
9 |
10 | | Client | [Resources] | [Prompts] | [Tools] | [Sampling] | Roots | Notes |
11 | | ------------------------------------ | ----------- | --------- | ------- | ---------- | ----- | ------------------------------------------------------------------ |
12 | | [Claude Desktop App][Claude] | ✅ | ✅ | ✅ | ❌ | ❌ | Full support for all MCP features |
13 | | [5ire][5ire] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
14 | | [BeeAI Framework][BeeAI Framework] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools in agentic workflows. |
15 | | [Cline][Cline] | ✅ | ❌ | ✅ | ❌ | ❌ | Supports tools and resources. |
16 | | [Continue][Continue] | ✅ | ✅ | ✅ | ❌ | ❌ | Full support for all MCP features |
17 | | [Cursor][Cursor] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
18 | | [Emacs Mcp][Mcp.el] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools in Emacs. |
19 | | [Firebase Genkit][Genkit] | ⚠️ | ✅ | ✅ | ❌ | ❌ | Supports resource list and lookup through tools. |
20 | | [GenAIScript][GenAIScript] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
21 | | [Goose][Goose] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
22 | | [LibreChat][LibreChat] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools for Agents |
23 | | [mcp-agent][mcp-agent] | ❌ | ❌ | ✅ | ⚠️ | ❌ | Supports tools, server connection management, and agent workflows. |
24 | | [Roo Code][Roo Code] | ✅ | ❌ | ✅ | ❌ | ❌ | Supports tools and resources. |
25 | | [Sourcegraph Cody][Cody] | ✅ | ❌ | ❌ | ❌ | ❌ | Supports resources through OpenCTX |
26 | | [Superinterface][Superinterface] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools |
27 | | [TheiaAI/TheiaIDE][TheiaAI/TheiaIDE] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools for Agents in Theia AI and the AI-powered Theia IDE |
28 | | [Windsurf Editor][Windsurf] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools with AI Flow for collaborative development. |
29 | | [Zed][Zed] | ❌ | ✅ | ❌ | ❌ | ❌ | Prompts appear as slash commands |
30 | | [SpinAI][SpinAI] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools for Typescript AI Agents |
31 | | [OpenSumi][OpenSumi] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools in OpenSumi |
32 | | [Daydreams Agents][Daydreams] | ✅ | ✅ | ✅ | ❌ | ❌ | Support for drop in Servers to Daydreams agents |
33 |
34 | [Claude]: https://claude.ai/download
35 |
36 | [Cursor]: https://cursor.com
37 |
38 | [Zed]: https://zed.dev
39 |
40 | [Cody]: https://sourcegraph.com/cody
41 |
42 | [Genkit]: https://github.com/firebase/genkit
43 |
44 | [Continue]: https://github.com/continuedev/continue
45 |
46 | [GenAIScript]: https://microsoft.github.io/genaiscript/reference/scripts/mcp-tools/
47 |
48 | [Cline]: https://github.com/cline/cline
49 |
50 | [LibreChat]: https://github.com/danny-avila/LibreChat
51 |
52 | [TheiaAI/TheiaIDE]: https://eclipsesource.com/blogs/2024/12/19/theia-ide-and-theia-ai-support-mcp/
53 |
54 | [Superinterface]: https://superinterface.ai
55 |
56 | [5ire]: https://github.com/nanbingxyz/5ire
57 |
58 | [BeeAI Framework]: https://i-am-bee.github.io/beeai-framework
59 |
60 | [mcp-agent]: https://github.com/lastmile-ai/mcp-agent
61 |
62 | [Mcp.el]: https://github.com/lizqwerscott/mcp.el
63 |
64 | [Roo Code]: https://roocode.com
65 |
66 | [Goose]: https://block.github.io/goose/docs/goose-architecture/#interoperability-with-extensions
67 |
68 | [Windsurf]: https://codeium.com/windsurf
69 |
70 | [Daydreams]: https://github.com/daydreamsai/daydreams
71 |
72 | [SpinAI]: https://spinai.dev
73 |
74 | [OpenSumi]: https://github.com/opensumi/core
75 |
76 | [Resources]: https://modelcontextprotocol.io/docs/concepts/resources
77 |
78 | [Prompts]: https://modelcontextprotocol.io/docs/concepts/prompts
79 |
80 | [Tools]: https://modelcontextprotocol.io/docs/concepts/tools
81 |
82 | [Sampling]: https://modelcontextprotocol.io/docs/concepts/sampling
83 |
84 | ## Client details
85 |
86 | ### Claude Desktop App
87 |
88 | The Claude desktop application provides comprehensive support for MCP, enabling deep integration with local tools and data sources.
89 |
90 | **Key features:**
91 |
92 | * Full support for resources, allowing attachment of local files and data
93 | * Support for prompt templates
94 | * Tool integration for executing commands and scripts
95 | * Local server connections for enhanced privacy and security
96 |
97 | > ⓘ Note: The Claude.ai web application does not currently support MCP. MCP features are only available in the desktop application.
98 |
99 | ### 5ire
100 |
101 | [5ire](https://github.com/nanbingxyz/5ire) is an open source cross-platform desktop AI assistant that supports tools through MCP servers.
102 |
103 | **Key features:**
104 |
105 | * Built-in MCP servers can be quickly enabled and disabled.
106 | * Users can add more servers by modifying the configuration file.
107 | * It is open-source and user-friendly, suitable for beginners.
108 | * Future support for MCP will be continuously improved.
109 |
110 | ### BeeAI Framework
111 |
112 | [BeeAI Framework](https://i-am-bee.github.io/beeai-framework) is an open-source framework for building, deploying, and serving powerful agentic workflows at scale. The framework includes the **MCP Tool**, a native feature that simplifies the integration of MCP servers into agentic workflows.
113 |
114 | **Key features:**
115 |
116 | * Seamlessly incorporate MCP tools into agentic workflows.
117 | * Quickly instantiate framework-native tools from connected MCP client(s).
118 | * Planned future support for agentic MCP capabilities.
119 |
120 | **Learn more:**
121 |
122 | * [Example of using MCP tools in agentic workflow](https://i-am-bee.github.io/beeai-framework/#/typescript/tools?id=using-the-mcptool-class)
123 |
124 | ### Cline
125 |
126 | [Cline](https://github.com/cline/cline) is an autonomous coding agent in VS Code that edits files, runs commands, uses a browser, and more–with your permission at each step.
127 |
128 | **Key features:**
129 |
130 | * Create and add tools through natural language (e.g. "add a tool that searches the web")
131 | * Share custom MCP servers Cline creates with others via the `~/Documents/Cline/MCP` directory
132 | * Displays configured MCP servers along with their tools, resources, and any error logs
133 |
134 | ### Continue
135 |
136 | [Continue](https://github.com/continuedev/continue) is an open-source AI code assistant, with built-in support for all MCP features.
137 |
138 | **Key features**
139 |
140 | * Type "@" to mention MCP resources
141 | * Prompt templates surface as slash commands
142 | * Use both built-in and MCP tools directly in chat
143 | * Supports VS Code and JetBrains IDEs, with any LLM
144 |
145 | ### Cursor
146 |
147 | [Cursor](https://docs.cursor.com/advanced/model-context-protocol) is an AI code editor.
148 |
149 | **Key Features**:
150 |
151 | * Support for MCP tools in Cursor Composer
152 | * Support for both STDIO and SSE
153 |
154 | ### Emacs Mcp
155 |
156 | [Emacs Mcp](https://github.com/lizqwerscott/mcp.el) is an Emacs client designed to interface with MCP servers, enabling seamless connections and interactions. It provides MCP tool invocation support for AI plugins like [gptel](https://github.com/karthink/gptel) and [llm](https://github.com/ahyatt/llm), adhering to Emacs' standard tool invocation format. This integration enhances the functionality of AI tools within the Emacs ecosystem.
157 |
158 | **Key features:**
159 |
160 | * Provides MCP tool support for Emacs.
161 |
162 | ### Firebase Genkit
163 |
164 | [Genkit](https://github.com/firebase/genkit) is Firebase's SDK for building and integrating GenAI features into applications. The [genkitx-mcp](https://github.com/firebase/genkit/tree/main/js/plugins/mcp) plugin enables consuming MCP servers as a client or creating MCP servers from Genkit tools and prompts.
165 |
166 | **Key features:**
167 |
168 | * Client support for tools and prompts (resources partially supported)
169 | * Rich discovery with support in Genkit's Dev UI playground
170 | * Seamless interoperability with Genkit's existing tools and prompts
171 | * Works across a wide variety of GenAI models from top providers
172 |
173 | ### GenAIScript
174 |
175 | Programmatically assemble prompts for LLMs using [GenAIScript](https://microsoft.github.io/genaiscript/) (in JavaScript). Orchestrate LLMs, tools, and data in JavaScript.
176 |
177 | **Key features:**
178 |
179 | * JavaScript toolbox to work with prompts
180 | * Abstraction to make it easy and productive
181 | * Seamless Visual Studio Code integration
182 |
183 | ### Goose
184 |
185 | [Goose](https://github.com/block/goose) is an open source AI agent that supercharges your software development by automating coding tasks.
186 |
187 | **Key features:**
188 |
189 | * Expose MCP functionality to Goose through tools.
190 | * MCPs can be installed directly via the [extensions directory](https://block.github.io/goose/v1/extensions/), CLI, or UI.
191 | * Goose allows you to extend its functionality by [building your own MCP servers](https://block.github.io/goose/docs/tutorials/custom-extensions).
192 | * Includes built-in tools for development, web scraping, automation, memory, and integrations with JetBrains and Google Drive.
193 |
194 | ### LibreChat
195 |
196 | [LibreChat](https://github.com/danny-avila/LibreChat) is an open-source, customizable AI chat UI that supports multiple AI providers, now including MCP integration.
197 |
198 | **Key features:**
199 |
200 | * Extend current tool ecosystem, including [Code Interpreter](https://www.librechat.ai/docs/features/code_interpreter) and Image generation tools, through MCP servers
201 | * Add tools to customizable [Agents](https://www.librechat.ai/docs/features/agents), using a variety of LLMs from top providers
202 | * Open-source and self-hostable, with secure multi-user support
203 | * Future roadmap includes expanded MCP feature support
204 |
205 | ### mcp-agent
206 |
207 | [mcp-agent] is a simple, composable framework to build agents using Model Context Protocol.
208 |
209 | **Key features:**
210 |
211 | * Automatic connection management of MCP servers.
212 | * Expose tools from multiple servers to an LLM.
213 | * Implements every pattern defined in [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents).
214 | * Supports workflow pause/resume signals, such as waiting for human feedback.
215 |
216 | ### Roo Code
217 |
218 | [Roo Code](https://roocode.com) enables AI coding assistance via MCP.
219 |
220 | **Key features:**
221 |
222 | * Support for MCP tools and resources
223 | * Integration with development workflows
224 | * Extensible AI capabilities
225 |
226 | ### Sourcegraph Cody
227 |
228 | [Cody](https://openctx.org/docs/providers/modelcontextprotocol) is Sourcegraph's AI coding assistant, which implements MCP through OpenCTX.
229 |
230 | **Key features:**
231 |
232 | * Support for MCP resources
233 | * Integration with Sourcegraph's code intelligence
234 | * Uses OpenCTX as an abstraction layer
235 | * Future support planned for additional MCP features
236 |
237 | ### SpinAI
238 |
239 | [SpinAI](https://spinai.dev) is an open-source TypeScript framework for building observable AI agents. The framework provides native MCP compatibility, allowing agents to seamlessly integrate with MCP servers and tools.
240 |
241 | **Key features:**
242 |
243 | * Built-in MCP compatibility for AI agents
244 | * Open-source TypeScript framework
245 | * Observable agent architecture
246 | * Native support for MCP tools integration
247 |
248 | ### Superinterface
249 |
250 | [Superinterface](https://superinterface.ai) is AI infrastructure and a developer platform to build in-app AI assistants with support for MCP, interactive components, client-side function calling and more.
251 |
252 | **Key features:**
253 |
254 | * Use tools from MCP servers in assistants embedded via React components or script tags
255 | * SSE transport support
256 | * Use any AI model from any AI provider (OpenAI, Anthropic, Ollama, others)
257 |
258 | ### TheiaAI/TheiaIDE
259 |
260 | [Theia AI](https://eclipsesource.com/blogs/2024/10/07/introducing-theia-ai/) is a framework for building AI-enhanced tools and IDEs. The [AI-powered Theia IDE](https://eclipsesource.com/blogs/2024/10/08/introducting-ai-theia-ide/) is an open and flexible development environment built on Theia AI.
261 |
262 | **Key features:**
263 |
264 | * **Tool Integration**: Theia AI enables AI agents, including those in the Theia IDE, to utilize MCP servers for seamless tool interaction.
265 | * **Customizable Prompts**: The Theia IDE allows users to define and adapt prompts, dynamically integrating MCP servers for tailored workflows.
266 | * **Custom agents**: The Theia IDE supports creating custom agents that leverage MCP capabilities, enabling users to design dedicated workflows on the fly.
267 |
268 | Theia AI and Theia IDE's MCP integration provide users with flexibility, making them powerful platforms for exploring and adapting MCP.
269 |
270 | **Learn more:**
271 |
272 | * [Theia IDE and Theia AI MCP Announcement](https://eclipsesource.com/blogs/2024/12/19/theia-ide-and-theia-ai-support-mcp/)
273 | * [Download the AI-powered Theia IDE](https://theia-ide.org/)
274 |
275 | ### Windsurf Editor
276 |
277 | [Windsurf Editor](https://codeium.com/windsurf) is an agentic IDE that combines AI assistance with developer workflows. It features an innovative AI Flow system that enables both collaborative and independent AI interactions while maintaining developer control.
278 |
279 | **Key features:**
280 |
281 | * Revolutionary AI Flow paradigm for human-AI collaboration
282 | * Intelligent code generation and understanding
283 | * Rich development tools with multi-model support
284 |
285 | ### Zed
286 |
287 | [Zed](https://zed.dev/docs/assistant/model-context-protocol) is a high-performance code editor with built-in MCP support, focusing on prompt templates and tool integration.
288 |
289 | **Key features:**
290 |
291 | * Prompt templates surface as slash commands in the editor
292 | * Tool integration for enhanced coding workflows
293 | * Tight integration with editor features and workspace context
294 | * Does not support MCP resources
295 |
296 | ### OpenSumi
297 |
298 | [OpenSumi](https://github.com/opensumi/core) is a framework helps you quickly build AI Native IDE products.
299 |
300 | **Key features:**
301 |
302 | * Supports MCP tools in OpenSumi
303 | * Supports built-in IDE MCP servers and custom MCP servers
304 |
305 | ### Daydreams
306 |
307 | [Daydreams](https://github.com/daydreamsai/daydreams) is a generative agent framework for executing anything onchain
308 |
309 | **Key features:**
310 |
311 | * Supports MCP Servers in config
312 | * Exposes MCP Client
313 |
314 | ## Adding MCP support to your application
315 |
316 | If you've added MCP support to your application, we encourage you to submit a pull request to add it to this list. MCP integration can provide your users with powerful contextual AI capabilities and make your application part of the growing MCP ecosystem.
317 |
318 | Benefits of adding MCP support:
319 |
320 | * Enable users to bring their own context and tools
321 | * Join a growing ecosystem of interoperable AI applications
322 | * Provide users with flexible integration options
323 | * Support local-first AI workflows
324 |
325 | To get started with implementing MCP in your application, check out our [Python](https://github.com/modelcontextprotocol/python-sdk) or [TypeScript SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
326 |
327 | ## Updates and corrections
328 |
329 | This list is maintained by the community. If you notice any inaccuracies or would like to update information about MCP support in your application, please submit a pull request or [open an issue in our documentation repository](https://github.com/modelcontextprotocol/docs/issues).
330 |
331 |
332 | # Contributing
333 | Source: https://modelcontextprotocol.io/development/contributing
334 |
335 | How to participate in Model Context Protocol development
336 |
337 | We welcome contributions from the community! Please review our [contributing guidelines](https://github.com/modelcontextprotocol/.github/blob/main/CONTRIBUTING.md) for details on how to submit changes.
338 |
339 | All contributors must adhere to our [Code of Conduct](https://github.com/modelcontextprotocol/.github/blob/main/CODE_OF_CONDUCT.md).
340 |
341 | For questions and discussions, please use [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions).
342 |
343 |
344 | # Roadmap
345 | Source: https://modelcontextprotocol.io/development/roadmap
346 |
347 | Our plans for evolving Model Context Protocol (H1 2025)
348 |
349 | The Model Context Protocol is rapidly evolving. This page outlines our current thinking on key priorities and future direction for **the first half of 2025**, though these may change significantly as the project develops.
350 |
351 | <Note>The ideas presented here are not commitments—we may solve these challenges differently than described, or some may not materialize at all. This is also not an *exhaustive* list; we may incorporate work that isn't mentioned here.</Note>
352 |
353 | We encourage community participation! Each section links to relevant discussions where you can learn more and contribute your thoughts.
354 |
355 | ## Remote MCP Support
356 |
357 | Our top priority is enabling [remote MCP connections](https://github.com/modelcontextprotocol/specification/discussions/102), allowing clients to securely connect to MCP servers over the internet. Key initiatives include:
358 |
359 | * [**Authentication & Authorization**](https://github.com/modelcontextprotocol/specification/discussions/64): Adding standardized auth capabilities, particularly focused on OAuth 2.0 support.
360 |
361 | * [**Service Discovery**](https://github.com/modelcontextprotocol/specification/discussions/69): Defining how clients can discover and connect to remote MCP servers.
362 |
363 | * [**Stateless Operations**](https://github.com/modelcontextprotocol/specification/discussions/102): Thinking about whether MCP could encompass serverless environments too, where they will need to be mostly stateless.
364 |
365 | ## Reference Implementations
366 |
367 | To help developers build with MCP, we want to offer documentation for:
368 |
369 | * **Client Examples**: Comprehensive reference client implementation(s), demonstrating all protocol features
370 | * **Protocol Drafting**: Streamlined process for proposing and incorporating new protocol features
371 |
372 | ## Distribution & Discovery
373 |
374 | Looking ahead, we're exploring ways to make MCP servers more accessible. Some areas we may investigate include:
375 |
376 | * **Package Management**: Standardized packaging format for MCP servers
377 | * **Installation Tools**: Simplified server installation across MCP clients
378 | * **Sandboxing**: Improved security through server isolation
379 | * **Server Registry**: A common directory for discovering available MCP servers
380 |
381 | ## Agent Support
382 |
383 | We're expanding MCP's capabilities for [complex agentic workflows](https://github.com/modelcontextprotocol/specification/discussions/111), particularly focusing on:
384 |
385 | * [**Hierarchical Agent Systems**](https://github.com/modelcontextprotocol/specification/discussions/94): Improved support for trees of agents through namespacing and topology awareness.
386 |
387 | * [**Interactive Workflows**](https://github.com/modelcontextprotocol/specification/issues/97): Better handling of user permissions and information requests across agent hierarchies, and ways to send output to users instead of models.
388 |
389 | * [**Streaming Results**](https://github.com/modelcontextprotocol/specification/issues/117): Real-time updates from long-running agent operations.
390 |
391 | ## Broader Ecosystem
392 |
393 | We're also invested in:
394 |
395 | * **Community-Led Standards Development**: Fostering a collaborative ecosystem where all AI providers can help shape MCP as an open standard through equal participation and shared governance, ensuring it meets the needs of diverse AI applications and use cases.
396 | * [**Additional Modalities**](https://github.com/modelcontextprotocol/specification/discussions/88): Expanding beyond text to support audio, video, and other formats.
397 | * \[**Standardization**] Considering standardization through a standardization body.
398 |
399 | ## Get Involved
400 |
401 | We welcome community participation in shaping MCP's future. Visit our [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions) to join the conversation and contribute your ideas.
402 |
403 |
404 | # What's New
405 | Source: https://modelcontextprotocol.io/development/updates
406 |
407 | The latest updates and improvements to MCP
408 |
409 | <Update label="2025-02-14" description="Java SDK released">
410 | * We're excited to announce that the Java SDK developed by Spring AI at VMware Tanzu is now
411 | the official [Java SDK](https://github.com/modelcontextprotocol/java-sdk) for MCP.
412 | This joins our existing Kotlin SDK in our growing list of supported languages.
413 | The Spring AI team will maintain the SDK as an integral part of the Model Context Protocol
414 | organization. We're thrilled to welcome them to the MCP community!
415 | </Update>
416 |
417 | <Update label="2025-01-27" description="Python SDK 1.2.1">
418 | * Version [1.2.1](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.2.1) of the MCP Python SDK has been released,
419 | delivering important stability improvements and bug fixes.
420 | </Update>
421 |
422 | <Update label="2025-01-18" description="SDK and Server Improvements">
423 | * Simplified, express-like API in the [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
424 | * Added 8 new clients to the [clients page](https://modelcontextprotocol.io/clients)
425 | </Update>
426 |
427 | <Update label="2025-01-03" description="SDK and Server Improvements">
428 | * FastMCP API in the [Python SDK](https://github.com/modelcontextprotocol/python-sdk)
429 | * Dockerized MCP servers in the [servers repo](https://github.com/modelcontextprotocol/servers)
430 | </Update>
431 |
432 | <Update label="2024-12-21" description="Kotlin SDK released">
433 | * Jetbrains released a Kotlin SDK for MCP!
434 | * For a sample MCP Kotlin server, check out [this repository](https://github.com/modelcontextprotocol/kotlin-sdk/tree/main/samples/kotlin-mcp-server)
435 | </Update>
436 |
437 |
438 | # Core architecture
439 | Source: https://modelcontextprotocol.io/docs/concepts/architecture
440 |
441 | Understand how MCP connects clients, servers, and LLMs
442 |
443 | The Model Context Protocol (MCP) is built on a flexible, extensible architecture that enables seamless communication between LLM applications and integrations. This document covers the core architectural components and concepts.
444 |
445 | ## Overview
446 |
447 | MCP follows a client-server architecture where:
448 |
449 | * **Hosts** are LLM applications (like Claude Desktop or IDEs) that initiate connections
450 | * **Clients** maintain 1:1 connections with servers, inside the host application
451 | * **Servers** provide context, tools, and prompts to clients
452 |
453 | ```mermaid
454 | flowchart LR
455 | subgraph "Host"
456 | client1[MCP Client]
457 | client2[MCP Client]
458 | end
459 | subgraph "Server Process"
460 | server1[MCP Server]
461 | end
462 | subgraph "Server Process"
463 | server2[MCP Server]
464 | end
465 |
466 | client1 <-->|Transport Layer| server1
467 | client2 <-->|Transport Layer| server2
468 | ```
469 |
470 | ## Core components
471 |
472 | ### Protocol layer
473 |
474 | The protocol layer handles message framing, request/response linking, and high-level communication patterns.
475 |
476 | <Tabs>
477 | <Tab title="TypeScript">
478 | ```typescript
479 | class Protocol<Request, Notification, Result> {
480 | // Handle incoming requests
481 | setRequestHandler<T>(schema: T, handler: (request: T, extra: RequestHandlerExtra) => Promise<Result>): void
482 |
483 | // Handle incoming notifications
484 | setNotificationHandler<T>(schema: T, handler: (notification: T) => Promise<void>): void
485 |
486 | // Send requests and await responses
487 | request<T>(request: Request, schema: T, options?: RequestOptions): Promise<T>
488 |
489 | // Send one-way notifications
490 | notification(notification: Notification): Promise<void>
491 | }
492 | ```
493 | </Tab>
494 |
495 | <Tab title="Python">
496 | ```python
497 | class Session(BaseSession[RequestT, NotificationT, ResultT]):
498 | async def send_request(
499 | self,
500 | request: RequestT,
501 | result_type: type[Result]
502 | ) -> Result:
503 | """
504 | Send request and wait for response. Raises McpError if response contains error.
505 | """
506 | # Request handling implementation
507 |
508 | async def send_notification(
509 | self,
510 | notification: NotificationT
511 | ) -> None:
512 | """Send one-way notification that doesn't expect response."""
513 | # Notification handling implementation
514 |
515 | async def _received_request(
516 | self,
517 | responder: RequestResponder[ReceiveRequestT, ResultT]
518 | ) -> None:
519 | """Handle incoming request from other side."""
520 | # Request handling implementation
521 |
522 | async def _received_notification(
523 | self,
524 | notification: ReceiveNotificationT
525 | ) -> None:
526 | """Handle incoming notification from other side."""
527 | # Notification handling implementation
528 | ```
529 | </Tab>
530 | </Tabs>
531 |
532 | Key classes include:
533 |
534 | * `Protocol`
535 | * `Client`
536 | * `Server`
537 |
538 | ### Transport layer
539 |
540 | The transport layer handles the actual communication between clients and servers. MCP supports multiple transport mechanisms:
541 |
542 | 1. **Stdio transport**
543 | * Uses standard input/output for communication
544 | * Ideal for local processes
545 |
546 | 2. **HTTP with SSE transport**
547 | * Uses Server-Sent Events for server-to-client messages
548 | * HTTP POST for client-to-server messages
549 |
550 | All transports use [JSON-RPC](https://www.jsonrpc.org/) 2.0 to exchange messages. See the [specification](https://spec.modelcontextprotocol.io) for detailed information about the Model Context Protocol message format.
551 |
552 | ### Message types
553 |
554 | MCP has these main types of messages:
555 |
556 | 1. **Requests** expect a response from the other side:
557 | ```typescript
558 | interface Request {
559 | method: string;
560 | params?: { ... };
561 | }
562 | ```
563 |
564 | 2. **Results** are successful responses to requests:
565 | ```typescript
566 | interface Result {
567 | [key: string]: unknown;
568 | }
569 | ```
570 |
571 | 3. **Errors** indicate that a request failed:
572 | ```typescript
573 | interface Error {
574 | code: number;
575 | message: string;
576 | data?: unknown;
577 | }
578 | ```
579 |
580 | 4. **Notifications** are one-way messages that don't expect a response:
581 | ```typescript
582 | interface Notification {
583 | method: string;
584 | params?: { ... };
585 | }
586 | ```
587 |
588 | ## Connection lifecycle
589 |
590 | ### 1. Initialization
591 |
592 | ```mermaid
593 | sequenceDiagram
594 | participant Client
595 | participant Server
596 |
597 | Client->>Server: initialize request
598 | Server->>Client: initialize response
599 | Client->>Server: initialized notification
600 |
601 | Note over Client,Server: Connection ready for use
602 | ```
603 |
604 | 1. Client sends `initialize` request with protocol version and capabilities
605 | 2. Server responds with its protocol version and capabilities
606 | 3. Client sends `initialized` notification as acknowledgment
607 | 4. Normal message exchange begins
608 |
609 | ### 2. Message exchange
610 |
611 | After initialization, the following patterns are supported:
612 |
613 | * **Request-Response**: Client or server sends requests, the other responds
614 | * **Notifications**: Either party sends one-way messages
615 |
616 | ### 3. Termination
617 |
618 | Either party can terminate the connection:
619 |
620 | * Clean shutdown via `close()`
621 | * Transport disconnection
622 | * Error conditions
623 |
624 | ## Error handling
625 |
626 | MCP defines these standard error codes:
627 |
628 | ```typescript
629 | enum ErrorCode {
630 | // Standard JSON-RPC error codes
631 | ParseError = -32700,
632 | InvalidRequest = -32600,
633 | MethodNotFound = -32601,
634 | InvalidParams = -32602,
635 | InternalError = -32603
636 | }
637 | ```
638 |
639 | SDKs and applications can define their own error codes above -32000.
640 |
641 | Errors are propagated through:
642 |
643 | * Error responses to requests
644 | * Error events on transports
645 | * Protocol-level error handlers
646 |
647 | ## Implementation example
648 |
649 | Here's a basic example of implementing an MCP server:
650 |
651 | <Tabs>
652 | <Tab title="TypeScript">
653 | ```typescript
654 | import { Server } from "@modelcontextprotocol/sdk/server/index.js";
655 | import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
656 |
657 | const server = new Server({
658 | name: "example-server",
659 | version: "1.0.0"
660 | }, {
661 | capabilities: {
662 | resources: {}
663 | }
664 | });
665 |
666 | // Handle requests
667 | server.setRequestHandler(ListResourcesRequestSchema, async () => {
668 | return {
669 | resources: [
670 | {
671 | uri: "example://resource",
672 | name: "Example Resource"
673 | }
674 | ]
675 | };
676 | });
677 |
678 | // Connect transport
679 | const transport = new StdioServerTransport();
680 | await server.connect(transport);
681 | ```
682 | </Tab>
683 |
684 | <Tab title="Python">
685 | ```python
686 | import asyncio
687 | import mcp.types as types
688 | from mcp.server import Server
689 | from mcp.server.stdio import stdio_server
690 |
691 | app = Server("example-server")
692 |
693 | @app.list_resources()
694 | async def list_resources() -> list[types.Resource]:
695 | return [
696 | types.Resource(
697 | uri="example://resource",
698 | name="Example Resource"
699 | )
700 | ]
701 |
702 | async def main():
703 | async with stdio_server() as streams:
704 | await app.run(
705 | streams[0],
706 | streams[1],
707 | app.create_initialization_options()
708 | )
709 |
710 | if __name__ == "__main__":
711 | asyncio.run(main)
712 | ```
713 | </Tab>
714 | </Tabs>
715 |
716 | ## Best practices
717 |
718 | ### Transport selection
719 |
720 | 1. **Local communication**
721 | * Use stdio transport for local processes
722 | * Efficient for same-machine communication
723 | * Simple process management
724 |
725 | 2. **Remote communication**
726 | * Use SSE for scenarios requiring HTTP compatibility
727 | * Consider security implications including authentication and authorization
728 |
729 | ### Message handling
730 |
731 | 1. **Request processing**
732 | * Validate inputs thoroughly
733 | * Use type-safe schemas
734 | * Handle errors gracefully
735 | * Implement timeouts
736 |
737 | 2. **Progress reporting**
738 | * Use progress tokens for long operations
739 | * Report progress incrementally
740 | * Include total progress when known
741 |
742 | 3. **Error management**
743 | * Use appropriate error codes
744 | * Include helpful error messages
745 | * Clean up resources on errors
746 |
747 | ## Security considerations
748 |
749 | 1. **Transport security**
750 | * Use TLS for remote connections
751 | * Validate connection origins
752 | * Implement authentication when needed
753 |
754 | 2. **Message validation**
755 | * Validate all incoming messages
756 | * Sanitize inputs
757 | * Check message size limits
758 | * Verify JSON-RPC format
759 |
760 | 3. **Resource protection**
761 | * Implement access controls
762 | * Validate resource paths
763 | * Monitor resource usage
764 | * Rate limit requests
765 |
766 | 4. **Error handling**
767 | * Don't leak sensitive information
768 | * Log security-relevant errors
769 | * Implement proper cleanup
770 | * Handle DoS scenarios
771 |
772 | ## Debugging and monitoring
773 |
774 | 1. **Logging**
775 | * Log protocol events
776 | * Track message flow
777 | * Monitor performance
778 | * Record errors
779 |
780 | 2. **Diagnostics**
781 | * Implement health checks
782 | * Monitor connection state
783 | * Track resource usage
784 | * Profile performance
785 |
786 | 3. **Testing**
787 | * Test different transports
788 | * Verify error handling
789 | * Check edge cases
790 | * Load test servers
791 |
792 |
793 | # Prompts
794 | Source: https://modelcontextprotocol.io/docs/concepts/prompts
795 |
796 | Create reusable prompt templates and workflows
797 |
798 | Prompts enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a powerful way to standardize and share common LLM interactions.
799 |
800 | <Note>
801 | Prompts are designed to be **user-controlled**, meaning they are exposed from servers to clients with the intention of the user being able to explicitly select them for use.
802 | </Note>
803 |
804 | ## Overview
805 |
806 | Prompts in MCP are predefined templates that can:
807 |
808 | * Accept dynamic arguments
809 | * Include context from resources
810 | * Chain multiple interactions
811 | * Guide specific workflows
812 | * Surface as UI elements (like slash commands)
813 |
814 | ## Prompt structure
815 |
816 | Each prompt is defined with:
817 |
818 | ```typescript
819 | {
820 | name: string; // Unique identifier for the prompt
821 | description?: string; // Human-readable description
822 | arguments?: [ // Optional list of arguments
823 | {
824 | name: string; // Argument identifier
825 | description?: string; // Argument description
826 | required?: boolean; // Whether argument is required
827 | }
828 | ]
829 | }
830 | ```
831 |
832 | ## Discovering prompts
833 |
834 | Clients can discover available prompts through the `prompts/list` endpoint:
835 |
836 | ```typescript
837 | // Request
838 | {
839 | method: "prompts/list"
840 | }
841 |
842 | // Response
843 | {
844 | prompts: [
845 | {
846 | name: "analyze-code",
847 | description: "Analyze code for potential improvements",
848 | arguments: [
849 | {
850 | name: "language",
851 | description: "Programming language",
852 | required: true
853 | }
854 | ]
855 | }
856 | ]
857 | }
858 | ```
859 |
860 | ## Using prompts
861 |
862 | To use a prompt, clients make a `prompts/get` request:
863 |
864 | ````typescript
865 | // Request
866 | {
867 | method: "prompts/get",
868 | params: {
869 | name: "analyze-code",
870 | arguments: {
871 | language: "python"
872 | }
873 | }
874 | }
875 |
876 | // Response
877 | {
878 | description: "Analyze Python code for potential improvements",
879 | messages: [
880 | {
881 | role: "user",
882 | content: {
883 | type: "text",
884 | text: "Please analyze the following Python code for potential improvements:\n\n```python\ndef calculate_sum(numbers):\n total = 0\n for num in numbers:\n total = total + num\n return total\n\nresult = calculate_sum([1, 2, 3, 4, 5])\nprint(result)\n```"
885 | }
886 | }
887 | ]
888 | }
889 | ````
890 |
891 | ## Dynamic prompts
892 |
893 | Prompts can be dynamic and include:
894 |
895 | ### Embedded resource context
896 |
897 | ```json
898 | {
899 | "name": "analyze-project",
900 | "description": "Analyze project logs and code",
901 | "arguments": [
902 | {
903 | "name": "timeframe",
904 | "description": "Time period to analyze logs",
905 | "required": true
906 | },
907 | {
908 | "name": "fileUri",
909 | "description": "URI of code file to review",
910 | "required": true
911 | }
912 | ]
913 | }
914 | ```
915 |
916 | When handling the `prompts/get` request:
917 |
918 | ```json
919 | {
920 | "messages": [
921 | {
922 | "role": "user",
923 | "content": {
924 | "type": "text",
925 | "text": "Analyze these system logs and the code file for any issues:"
926 | }
927 | },
928 | {
929 | "role": "user",
930 | "content": {
931 | "type": "resource",
932 | "resource": {
933 | "uri": "logs://recent?timeframe=1h",
934 | "text": "[2024-03-14 15:32:11] ERROR: Connection timeout in network.py:127\n[2024-03-14 15:32:15] WARN: Retrying connection (attempt 2/3)\n[2024-03-14 15:32:20] ERROR: Max retries exceeded",
935 | "mimeType": "text/plain"
936 | }
937 | }
938 | },
939 | {
940 | "role": "user",
941 | "content": {
942 | "type": "resource",
943 | "resource": {
944 | "uri": "file:///path/to/code.py",
945 | "text": "def connect_to_service(timeout=30):\n retries = 3\n for attempt in range(retries):\n try:\n return establish_connection(timeout)\n except TimeoutError:\n if attempt == retries - 1:\n raise\n time.sleep(5)\n\ndef establish_connection(timeout):\n # Connection implementation\n pass",
946 | "mimeType": "text/x-python"
947 | }
948 | }
949 | }
950 | ]
951 | }
952 | ```
953 |
954 | ### Multi-step workflows
955 |
956 | ```typescript
957 | const debugWorkflow = {
958 | name: "debug-error",
959 | async getMessages(error: string) {
960 | return [
961 | {
962 | role: "user",
963 | content: {
964 | type: "text",
965 | text: `Here's an error I'm seeing: ${error}`
966 | }
967 | },
968 | {
969 | role: "assistant",
970 | content: {
971 | type: "text",
972 | text: "I'll help analyze this error. What have you tried so far?"
973 | }
974 | },
975 | {
976 | role: "user",
977 | content: {
978 | type: "text",
979 | text: "I've tried restarting the service, but the error persists."
980 | }
981 | }
982 | ];
983 | }
984 | };
985 | ```
986 |
987 | ## Example implementation
988 |
989 | Here's a complete example of implementing prompts in an MCP server:
990 |
991 | <Tabs>
992 | <Tab title="TypeScript">
993 | ```typescript
994 | import { Server } from "@modelcontextprotocol/sdk/server";
995 | import {
996 | ListPromptsRequestSchema,
997 | GetPromptRequestSchema
998 | } from "@modelcontextprotocol/sdk/types";
999 |
1000 | const PROMPTS = {
1001 | "git-commit": {
1002 | name: "git-commit",
1003 | description: "Generate a Git commit message",
1004 | arguments: [
1005 | {
1006 | name: "changes",
1007 | description: "Git diff or description of changes",
1008 | required: true
1009 | }
1010 | ]
1011 | },
1012 | "explain-code": {
1013 | name: "explain-code",
1014 | description: "Explain how code works",
1015 | arguments: [
1016 | {
1017 | name: "code",
1018 | description: "Code to explain",
1019 | required: true
1020 | },
1021 | {
1022 | name: "language",
1023 | description: "Programming language",
1024 | required: false
1025 | }
1026 | ]
1027 | }
1028 | };
1029 |
1030 | const server = new Server({
1031 | name: "example-prompts-server",
1032 | version: "1.0.0"
1033 | }, {
1034 | capabilities: {
1035 | prompts: {}
1036 | }
1037 | });
1038 |
1039 | // List available prompts
1040 | server.setRequestHandler(ListPromptsRequestSchema, async () => {
1041 | return {
1042 | prompts: Object.values(PROMPTS)
1043 | };
1044 | });
1045 |
1046 | // Get specific prompt
1047 | server.setRequestHandler(GetPromptRequestSchema, async (request) => {
1048 | const prompt = PROMPTS[request.params.name];
1049 | if (!prompt) {
1050 | throw new Error(`Prompt not found: ${request.params.name}`);
1051 | }
1052 |
1053 | if (request.params.name === "git-commit") {
1054 | return {
1055 | messages: [
1056 | {
1057 | role: "user",
1058 | content: {
1059 | type: "text",
1060 | text: `Generate a concise but descriptive commit message for these changes:\n\n${request.params.arguments?.changes}`
1061 | }
1062 | }
1063 | ]
1064 | };
1065 | }
1066 |
1067 | if (request.params.name === "explain-code") {
1068 | const language = request.params.arguments?.language || "Unknown";
1069 | return {
1070 | messages: [
1071 | {
1072 | role: "user",
1073 | content: {
1074 | type: "text",
1075 | text: `Explain how this ${language} code works:\n\n${request.params.arguments?.code}`
1076 | }
1077 | }
1078 | ]
1079 | };
1080 | }
1081 |
1082 | throw new Error("Prompt implementation not found");
1083 | });
1084 | ```
1085 | </Tab>
1086 |
1087 | <Tab title="Python">
1088 | ```python
1089 | from mcp.server import Server
1090 | import mcp.types as types
1091 |
1092 | # Define available prompts
1093 | PROMPTS = {
1094 | "git-commit": types.Prompt(
1095 | name="git-commit",
1096 | description="Generate a Git commit message",
1097 | arguments=[
1098 | types.PromptArgument(
1099 | name="changes",
1100 | description="Git diff or description of changes",
1101 | required=True
1102 | )
1103 | ],
1104 | ),
1105 | "explain-code": types.Prompt(
1106 | name="explain-code",
1107 | description="Explain how code works",
1108 | arguments=[
1109 | types.PromptArgument(
1110 | name="code",
1111 | description="Code to explain",
1112 | required=True
1113 | ),
1114 | types.PromptArgument(
1115 | name="language",
1116 | description="Programming language",
1117 | required=False
1118 | )
1119 | ],
1120 | )
1121 | }
1122 |
1123 | # Initialize server
1124 | app = Server("example-prompts-server")
1125 |
1126 | @app.list_prompts()
1127 | async def list_prompts() -> list[types.Prompt]:
1128 | return list(PROMPTS.values())
1129 |
1130 | @app.get_prompt()
1131 | async def get_prompt(
1132 | name: str, arguments: dict[str, str] | None = None
1133 | ) -> types.GetPromptResult:
1134 | if name not in PROMPTS:
1135 | raise ValueError(f"Prompt not found: {name}")
1136 |
1137 | if name == "git-commit":
1138 | changes = arguments.get("changes") if arguments else ""
1139 | return types.GetPromptResult(
1140 | messages=[
1141 | types.PromptMessage(
1142 | role="user",
1143 | content=types.TextContent(
1144 | type="text",
1145 | text=f"Generate a concise but descriptive commit message "
1146 | f"for these changes:\n\n{changes}"
1147 | )
1148 | )
1149 | ]
1150 | )
1151 |
1152 | if name == "explain-code":
1153 | code = arguments.get("code") if arguments else ""
1154 | language = arguments.get("language", "Unknown") if arguments else "Unknown"
1155 | return types.GetPromptResult(
1156 | messages=[
1157 | types.PromptMessage(
1158 | role="user",
1159 | content=types.TextContent(
1160 | type="text",
1161 | text=f"Explain how this {language} code works:\n\n{code}"
1162 | )
1163 | )
1164 | ]
1165 | )
1166 |
1167 | raise ValueError("Prompt implementation not found")
1168 | ```
1169 | </Tab>
1170 | </Tabs>
1171 |
1172 | ## Best practices
1173 |
1174 | When implementing prompts:
1175 |
1176 | 1. Use clear, descriptive prompt names
1177 | 2. Provide detailed descriptions for prompts and arguments
1178 | 3. Validate all required arguments
1179 | 4. Handle missing arguments gracefully
1180 | 5. Consider versioning for prompt templates
1181 | 6. Cache dynamic content when appropriate
1182 | 7. Implement error handling
1183 | 8. Document expected argument formats
1184 | 9. Consider prompt composability
1185 | 10. Test prompts with various inputs
1186 |
1187 | ## UI integration
1188 |
1189 | Prompts can be surfaced in client UIs as:
1190 |
1191 | * Slash commands
1192 | * Quick actions
1193 | * Context menu items
1194 | * Command palette entries
1195 | * Guided workflows
1196 | * Interactive forms
1197 |
1198 | ## Updates and changes
1199 |
1200 | Servers can notify clients about prompt changes:
1201 |
1202 | 1. Server capability: `prompts.listChanged`
1203 | 2. Notification: `notifications/prompts/list_changed`
1204 | 3. Client re-fetches prompt list
1205 |
1206 | ## Security considerations
1207 |
1208 | When implementing prompts:
1209 |
1210 | * Validate all arguments
1211 | * Sanitize user input
1212 | * Consider rate limiting
1213 | * Implement access controls
1214 | * Audit prompt usage
1215 | * Handle sensitive data appropriately
1216 | * Validate generated content
1217 | * Implement timeouts
1218 | * Consider prompt injection risks
1219 | * Document security requirements
1220 |
1221 |
1222 | # Resources
1223 | Source: https://modelcontextprotocol.io/docs/concepts/resources
1224 |
1225 | Expose data and content from your servers to LLMs
1226 |
1227 | Resources are a core primitive in the Model Context Protocol (MCP) that allow servers to expose data and content that can be read by clients and used as context for LLM interactions.
1228 |
1229 | <Note>
1230 | Resources are designed to be **application-controlled**, meaning that the client application can decide how and when they should be used.
1231 | Different MCP clients may handle resources differently. For example:
1232 |
1233 | * Claude Desktop currently requires users to explicitly select resources before they can be used
1234 | * Other clients might automatically select resources based on heuristics
1235 | * Some implementations may even allow the AI model itself to determine which resources to use
1236 |
1237 | Server authors should be prepared to handle any of these interaction patterns when implementing resource support. In order to expose data to models automatically, server authors should use a **model-controlled** primitive such as [Tools](./tools).
1238 | </Note>
1239 |
1240 | ## Overview
1241 |
1242 | Resources represent any kind of data that an MCP server wants to make available to clients. This can include:
1243 |
1244 | * File contents
1245 | * Database records
1246 | * API responses
1247 | * Live system data
1248 | * Screenshots and images
1249 | * Log files
1250 | * And more
1251 |
1252 | Each resource is identified by a unique URI and can contain either text or binary data.
1253 |
1254 | ## Resource URIs
1255 |
1256 | Resources are identified using URIs that follow this format:
1257 |
1258 | ```
1259 | [protocol]://[host]/[path]
1260 | ```
1261 |
1262 | For example:
1263 |
1264 | * `file:///home/user/documents/report.pdf`
1265 | * `postgres://database/customers/schema`
1266 | * `screen://localhost/display1`
1267 |
1268 | The protocol and path structure is defined by the MCP server implementation. Servers can define their own custom URI schemes.
1269 |
1270 | ## Resource types
1271 |
1272 | Resources can contain two types of content:
1273 |
1274 | ### Text resources
1275 |
1276 | Text resources contain UTF-8 encoded text data. These are suitable for:
1277 |
1278 | * Source code
1279 | * Configuration files
1280 | * Log files
1281 | * JSON/XML data
1282 | * Plain text
1283 |
1284 | ### Binary resources
1285 |
1286 | Binary resources contain raw binary data encoded in base64. These are suitable for:
1287 |
1288 | * Images
1289 | * PDFs
1290 | * Audio files
1291 | * Video files
1292 | * Other non-text formats
1293 |
1294 | ## Resource discovery
1295 |
1296 | Clients can discover available resources through two main methods:
1297 |
1298 | ### Direct resources
1299 |
1300 | Servers expose a list of concrete resources via the `resources/list` endpoint. Each resource includes:
1301 |
1302 | ```typescript
1303 | {
1304 | uri: string; // Unique identifier for the resource
1305 | name: string; // Human-readable name
1306 | description?: string; // Optional description
1307 | mimeType?: string; // Optional MIME type
1308 | }
1309 | ```
1310 |
1311 | ### Resource templates
1312 |
1313 | For dynamic resources, servers can expose [URI templates](https://datatracker.ietf.org/doc/html/rfc6570) that clients can use to construct valid resource URIs:
1314 |
1315 | ```typescript
1316 | {
1317 | uriTemplate: string; // URI template following RFC 6570
1318 | name: string; // Human-readable name for this type
1319 | description?: string; // Optional description
1320 | mimeType?: string; // Optional MIME type for all matching resources
1321 | }
1322 | ```
1323 |
1324 | ## Reading resources
1325 |
1326 | To read a resource, clients make a `resources/read` request with the resource URI.
1327 |
1328 | The server responds with a list of resource contents:
1329 |
1330 | ```typescript
1331 | {
1332 | contents: [
1333 | {
1334 | uri: string; // The URI of the resource
1335 | mimeType?: string; // Optional MIME type
1336 |
1337 | // One of:
1338 | text?: string; // For text resources
1339 | blob?: string; // For binary resources (base64 encoded)
1340 | }
1341 | ]
1342 | }
1343 | ```
1344 |
1345 | <Tip>
1346 | Servers may return multiple resources in response to one `resources/read` request. This could be used, for example, to return a list of files inside a directory when the directory is read.
1347 | </Tip>
1348 |
1349 | ## Resource updates
1350 |
1351 | MCP supports real-time updates for resources through two mechanisms:
1352 |
1353 | ### List changes
1354 |
1355 | Servers can notify clients when their list of available resources changes via the `notifications/resources/list_changed` notification.
1356 |
1357 | ### Content changes
1358 |
1359 | Clients can subscribe to updates for specific resources:
1360 |
1361 | 1. Client sends `resources/subscribe` with resource URI
1362 | 2. Server sends `notifications/resources/updated` when the resource changes
1363 | 3. Client can fetch latest content with `resources/read`
1364 | 4. Client can unsubscribe with `resources/unsubscribe`
1365 |
1366 | ## Example implementation
1367 |
1368 | Here's a simple example of implementing resource support in an MCP server:
1369 |
1370 | <Tabs>
1371 | <Tab title="TypeScript">
1372 | ```typescript
1373 | const server = new Server({
1374 | name: "example-server",
1375 | version: "1.0.0"
1376 | }, {
1377 | capabilities: {
1378 | resources: {}
1379 | }
1380 | });
1381 |
1382 | // List available resources
1383 | server.setRequestHandler(ListResourcesRequestSchema, async () => {
1384 | return {
1385 | resources: [
1386 | {
1387 | uri: "file:///logs/app.log",
1388 | name: "Application Logs",
1389 | mimeType: "text/plain"
1390 | }
1391 | ]
1392 | };
1393 | });
1394 |
1395 | // Read resource contents
1396 | server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
1397 | const uri = request.params.uri;
1398 |
1399 | if (uri === "file:///logs/app.log") {
1400 | const logContents = await readLogFile();
1401 | return {
1402 | contents: [
1403 | {
1404 | uri,
1405 | mimeType: "text/plain",
1406 | text: logContents
1407 | }
1408 | ]
1409 | };
1410 | }
1411 |
1412 | throw new Error("Resource not found");
1413 | });
1414 | ```
1415 | </Tab>
1416 |
1417 | <Tab title="Python">
1418 | ```python
1419 | app = Server("example-server")
1420 |
1421 | @app.list_resources()
1422 | async def list_resources() -> list[types.Resource]:
1423 | return [
1424 | types.Resource(
1425 | uri="file:///logs/app.log",
1426 | name="Application Logs",
1427 | mimeType="text/plain"
1428 | )
1429 | ]
1430 |
1431 | @app.read_resource()
1432 | async def read_resource(uri: AnyUrl) -> str:
1433 | if str(uri) == "file:///logs/app.log":
1434 | log_contents = await read_log_file()
1435 | return log_contents
1436 |
1437 | raise ValueError("Resource not found")
1438 |
1439 | # Start server
1440 | async with stdio_server() as streams:
1441 | await app.run(
1442 | streams[0],
1443 | streams[1],
1444 | app.create_initialization_options()
1445 | )
1446 | ```
1447 | </Tab>
1448 | </Tabs>
1449 |
1450 | ## Best practices
1451 |
1452 | When implementing resource support:
1453 |
1454 | 1. Use clear, descriptive resource names and URIs
1455 | 2. Include helpful descriptions to guide LLM understanding
1456 | 3. Set appropriate MIME types when known
1457 | 4. Implement resource templates for dynamic content
1458 | 5. Use subscriptions for frequently changing resources
1459 | 6. Handle errors gracefully with clear error messages
1460 | 7. Consider pagination for large resource lists
1461 | 8. Cache resource contents when appropriate
1462 | 9. Validate URIs before processing
1463 | 10. Document your custom URI schemes
1464 |
1465 | ## Security considerations
1466 |
1467 | When exposing resources:
1468 |
1469 | * Validate all resource URIs
1470 | * Implement appropriate access controls
1471 | * Sanitize file paths to prevent directory traversal
1472 | * Be cautious with binary data handling
1473 | * Consider rate limiting for resource reads
1474 | * Audit resource access
1475 | * Encrypt sensitive data in transit
1476 | * Validate MIME types
1477 | * Implement timeouts for long-running reads
1478 | * Handle resource cleanup appropriately
1479 |
1480 |
1481 | # Roots
1482 | Source: https://modelcontextprotocol.io/docs/concepts/roots
1483 |
1484 | Understanding roots in MCP
1485 |
1486 | Roots are a concept in MCP that define the boundaries where servers can operate. They provide a way for clients to inform servers about relevant resources and their locations.
1487 |
1488 | ## What are Roots?
1489 |
1490 | A root is a URI that a client suggests a server should focus on. When a client connects to a server, it declares which roots the server should work with. While primarily used for filesystem paths, roots can be any valid URI including HTTP URLs.
1491 |
1492 | For example, roots could be:
1493 |
1494 | ```
1495 | file:///home/user/projects/myapp
1496 | https://api.example.com/v1
1497 | ```
1498 |
1499 | ## Why Use Roots?
1500 |
1501 | Roots serve several important purposes:
1502 |
1503 | 1. **Guidance**: They inform servers about relevant resources and locations
1504 | 2. **Clarity**: Roots make it clear which resources are part of your workspace
1505 | 3. **Organization**: Multiple roots let you work with different resources simultaneously
1506 |
1507 | ## How Roots Work
1508 |
1509 | When a client supports roots, it:
1510 |
1511 | 1. Declares the `roots` capability during connection
1512 | 2. Provides a list of suggested roots to the server
1513 | 3. Notifies the server when roots change (if supported)
1514 |
1515 | While roots are informational and not strictly enforcing, servers should:
1516 |
1517 | 1. Respect the provided roots
1518 | 2. Use root URIs to locate and access resources
1519 | 3. Prioritize operations within root boundaries
1520 |
1521 | ## Common Use Cases
1522 |
1523 | Roots are commonly used to define:
1524 |
1525 | * Project directories
1526 | * Repository locations
1527 | * API endpoints
1528 | * Configuration locations
1529 | * Resource boundaries
1530 |
1531 | ## Best Practices
1532 |
1533 | When working with roots:
1534 |
1535 | 1. Only suggest necessary resources
1536 | 2. Use clear, descriptive names for roots
1537 | 3. Monitor root accessibility
1538 | 4. Handle root changes gracefully
1539 |
1540 | ## Example
1541 |
1542 | Here's how a typical MCP client might expose roots:
1543 |
1544 | ```json
1545 | {
1546 | "roots": [
1547 | {
1548 | "uri": "file:///home/user/projects/frontend",
1549 | "name": "Frontend Repository"
1550 | },
1551 | {
1552 | "uri": "https://api.example.com/v1",
1553 | "name": "API Endpoint"
1554 | }
1555 | ]
1556 | }
1557 | ```
1558 |
1559 | This configuration suggests the server focus on both a local repository and an API endpoint while keeping them logically separated.
1560 |
1561 |
1562 | # Sampling
1563 | Source: https://modelcontextprotocol.io/docs/concepts/sampling
1564 |
1565 | Let your servers request completions from LLMs
1566 |
1567 | Sampling is a powerful MCP feature that allows servers to request LLM completions through the client, enabling sophisticated agentic behaviors while maintaining security and privacy.
1568 |
1569 | <Info>
1570 | This feature of MCP is not yet supported in the Claude Desktop client.
1571 | </Info>
1572 |
1573 | ## How sampling works
1574 |
1575 | The sampling flow follows these steps:
1576 |
1577 | 1. Server sends a `sampling/createMessage` request to the client
1578 | 2. Client reviews the request and can modify it
1579 | 3. Client samples from an LLM
1580 | 4. Client reviews the completion
1581 | 5. Client returns the result to the server
1582 |
1583 | This human-in-the-loop design ensures users maintain control over what the LLM sees and generates.
1584 |
1585 | ## Message format
1586 |
1587 | Sampling requests use a standardized message format:
1588 |
1589 | ```typescript
1590 | {
1591 | messages: [
1592 | {
1593 | role: "user" | "assistant",
1594 | content: {
1595 | type: "text" | "image",
1596 |
1597 | // For text:
1598 | text?: string,
1599 |
1600 | // For images:
1601 | data?: string, // base64 encoded
1602 | mimeType?: string
1603 | }
1604 | }
1605 | ],
1606 | modelPreferences?: {
1607 | hints?: [{
1608 | name?: string // Suggested model name/family
1609 | }],
1610 | costPriority?: number, // 0-1, importance of minimizing cost
1611 | speedPriority?: number, // 0-1, importance of low latency
1612 | intelligencePriority?: number // 0-1, importance of capabilities
1613 | },
1614 | systemPrompt?: string,
1615 | includeContext?: "none" | "thisServer" | "allServers",
1616 | temperature?: number,
1617 | maxTokens: number,
1618 | stopSequences?: string[],
1619 | metadata?: Record<string, unknown>
1620 | }
1621 | ```
1622 |
1623 | ## Request parameters
1624 |
1625 | ### Messages
1626 |
1627 | The `messages` array contains the conversation history to send to the LLM. Each message has:
1628 |
1629 | * `role`: Either "user" or "assistant"
1630 | * `content`: The message content, which can be:
1631 | * Text content with a `text` field
1632 | * Image content with `data` (base64) and `mimeType` fields
1633 |
1634 | ### Model preferences
1635 |
1636 | The `modelPreferences` object allows servers to specify their model selection preferences:
1637 |
1638 | * `hints`: Array of model name suggestions that clients can use to select an appropriate model:
1639 | * `name`: String that can match full or partial model names (e.g. "claude-3", "sonnet")
1640 | * Clients may map hints to equivalent models from different providers
1641 | * Multiple hints are evaluated in preference order
1642 |
1643 | * Priority values (0-1 normalized):
1644 | * `costPriority`: Importance of minimizing costs
1645 | * `speedPriority`: Importance of low latency response
1646 | * `intelligencePriority`: Importance of advanced model capabilities
1647 |
1648 | Clients make the final model selection based on these preferences and their available models.
1649 |
1650 | ### System prompt
1651 |
1652 | An optional `systemPrompt` field allows servers to request a specific system prompt. The client may modify or ignore this.
1653 |
1654 | ### Context inclusion
1655 |
1656 | The `includeContext` parameter specifies what MCP context to include:
1657 |
1658 | * `"none"`: No additional context
1659 | * `"thisServer"`: Include context from the requesting server
1660 | * `"allServers"`: Include context from all connected MCP servers
1661 |
1662 | The client controls what context is actually included.
1663 |
1664 | ### Sampling parameters
1665 |
1666 | Fine-tune the LLM sampling with:
1667 |
1668 | * `temperature`: Controls randomness (0.0 to 1.0)
1669 | * `maxTokens`: Maximum tokens to generate
1670 | * `stopSequences`: Array of sequences that stop generation
1671 | * `metadata`: Additional provider-specific parameters
1672 |
1673 | ## Response format
1674 |
1675 | The client returns a completion result:
1676 |
1677 | ```typescript
1678 | {
1679 | model: string, // Name of the model used
1680 | stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string,
1681 | role: "user" | "assistant",
1682 | content: {
1683 | type: "text" | "image",
1684 | text?: string,
1685 | data?: string,
1686 | mimeType?: string
1687 | }
1688 | }
1689 | ```
1690 |
1691 | ## Example request
1692 |
1693 | Here's an example of requesting sampling from a client:
1694 |
1695 | ```json
1696 | {
1697 | "method": "sampling/createMessage",
1698 | "params": {
1699 | "messages": [
1700 | {
1701 | "role": "user",
1702 | "content": {
1703 | "type": "text",
1704 | "text": "What files are in the current directory?"
1705 | }
1706 | }
1707 | ],
1708 | "systemPrompt": "You are a helpful file system assistant.",
1709 | "includeContext": "thisServer",
1710 | "maxTokens": 100
1711 | }
1712 | }
1713 | ```
1714 |
1715 | ## Best practices
1716 |
1717 | When implementing sampling:
1718 |
1719 | 1. Always provide clear, well-structured prompts
1720 | 2. Handle both text and image content appropriately
1721 | 3. Set reasonable token limits
1722 | 4. Include relevant context through `includeContext`
1723 | 5. Validate responses before using them
1724 | 6. Handle errors gracefully
1725 | 7. Consider rate limiting sampling requests
1726 | 8. Document expected sampling behavior
1727 | 9. Test with various model parameters
1728 | 10. Monitor sampling costs
1729 |
1730 | ## Human in the loop controls
1731 |
1732 | Sampling is designed with human oversight in mind:
1733 |
1734 | ### For prompts
1735 |
1736 | * Clients should show users the proposed prompt
1737 | * Users should be able to modify or reject prompts
1738 | * System prompts can be filtered or modified
1739 | * Context inclusion is controlled by the client
1740 |
1741 | ### For completions
1742 |
1743 | * Clients should show users the completion
1744 | * Users should be able to modify or reject completions
1745 | * Clients can filter or modify completions
1746 | * Users control which model is used
1747 |
1748 | ## Security considerations
1749 |
1750 | When implementing sampling:
1751 |
1752 | * Validate all message content
1753 | * Sanitize sensitive information
1754 | * Implement appropriate rate limits
1755 | * Monitor sampling usage
1756 | * Encrypt data in transit
1757 | * Handle user data privacy
1758 | * Audit sampling requests
1759 | * Control cost exposure
1760 | * Implement timeouts
1761 | * Handle model errors gracefully
1762 |
1763 | ## Common patterns
1764 |
1765 | ### Agentic workflows
1766 |
1767 | Sampling enables agentic patterns like:
1768 |
1769 | * Reading and analyzing resources
1770 | * Making decisions based on context
1771 | * Generating structured data
1772 | * Handling multi-step tasks
1773 | * Providing interactive assistance
1774 |
1775 | ### Context management
1776 |
1777 | Best practices for context:
1778 |
1779 | * Request minimal necessary context
1780 | * Structure context clearly
1781 | * Handle context size limits
1782 | * Update context as needed
1783 | * Clean up stale context
1784 |
1785 | ### Error handling
1786 |
1787 | Robust error handling should:
1788 |
1789 | * Catch sampling failures
1790 | * Handle timeout errors
1791 | * Manage rate limits
1792 | * Validate responses
1793 | * Provide fallback behaviors
1794 | * Log errors appropriately
1795 |
1796 | ## Limitations
1797 |
1798 | Be aware of these limitations:
1799 |
1800 | * Sampling depends on client capabilities
1801 | * Users control sampling behavior
1802 | * Context size has limits
1803 | * Rate limits may apply
1804 | * Costs should be considered
1805 | * Model availability varies
1806 | * Response times vary
1807 | * Not all content types supported
1808 |
1809 |
1810 | # Tools
1811 | Source: https://modelcontextprotocol.io/docs/concepts/tools
1812 |
1813 | Enable LLMs to perform actions through your server
1814 |
1815 | Tools are a powerful primitive in the Model Context Protocol (MCP) that enable servers to expose executable functionality to clients. Through tools, LLMs can interact with external systems, perform computations, and take actions in the real world.
1816 |
1817 | <Note>
1818 | Tools are designed to be **model-controlled**, meaning that tools are exposed from servers to clients with the intention of the AI model being able to automatically invoke them (with a human in the loop to grant approval).
1819 | </Note>
1820 |
1821 | ## Overview
1822 |
1823 | Tools in MCP allow servers to expose executable functions that can be invoked by clients and used by LLMs to perform actions. Key aspects of tools include:
1824 |
1825 | * **Discovery**: Clients can list available tools through the `tools/list` endpoint
1826 | * **Invocation**: Tools are called using the `tools/call` endpoint, where servers perform the requested operation and return results
1827 | * **Flexibility**: Tools can range from simple calculations to complex API interactions
1828 |
1829 | Like [resources](/docs/concepts/resources), tools are identified by unique names and can include descriptions to guide their usage. However, unlike resources, tools represent dynamic operations that can modify state or interact with external systems.
1830 |
1831 | ## Tool definition structure
1832 |
1833 | Each tool is defined with the following structure:
1834 |
1835 | ```typescript
1836 | {
1837 | name: string; // Unique identifier for the tool
1838 | description?: string; // Human-readable description
1839 | inputSchema: { // JSON Schema for the tool's parameters
1840 | type: "object",
1841 | properties: { ... } // Tool-specific parameters
1842 | }
1843 | }
1844 | ```
1845 |
1846 | ## Implementing tools
1847 |
1848 | Here's an example of implementing a basic tool in an MCP server:
1849 |
1850 | <Tabs>
1851 | <Tab title="TypeScript">
1852 | ```typescript
1853 | const server = new Server({
1854 | name: "example-server",
1855 | version: "1.0.0"
1856 | }, {
1857 | capabilities: {
1858 | tools: {}
1859 | }
1860 | });
1861 |
1862 | // Define available tools
1863 | server.setRequestHandler(ListToolsRequestSchema, async () => {
1864 | return {
1865 | tools: [{
1866 | name: "calculate_sum",
1867 | description: "Add two numbers together",
1868 | inputSchema: {
1869 | type: "object",
1870 | properties: {
1871 | a: { type: "number" },
1872 | b: { type: "number" }
1873 | },
1874 | required: ["a", "b"]
1875 | }
1876 | }]
1877 | };
1878 | });
1879 |
1880 | // Handle tool execution
1881 | server.setRequestHandler(CallToolRequestSchema, async (request) => {
1882 | if (request.params.name === "calculate_sum") {
1883 | const { a, b } = request.params.arguments;
1884 | return {
1885 | content: [
1886 | {
1887 | type: "text",
1888 | text: String(a + b)
1889 | }
1890 | ]
1891 | };
1892 | }
1893 | throw new Error("Tool not found");
1894 | });
1895 | ```
1896 | </Tab>
1897 |
1898 | <Tab title="Python">
1899 | ```python
1900 | app = Server("example-server")
1901 |
1902 | @app.list_tools()
1903 | async def list_tools() -> list[types.Tool]:
1904 | return [
1905 | types.Tool(
1906 | name="calculate_sum",
1907 | description="Add two numbers together",
1908 | inputSchema={
1909 | "type": "object",
1910 | "properties": {
1911 | "a": {"type": "number"},
1912 | "b": {"type": "number"}
1913 | },
1914 | "required": ["a", "b"]
1915 | }
1916 | )
1917 | ]
1918 |
1919 | @app.call_tool()
1920 | async def call_tool(
1921 | name: str,
1922 | arguments: dict
1923 | ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
1924 | if name == "calculate_sum":
1925 | a = arguments["a"]
1926 | b = arguments["b"]
1927 | result = a + b
1928 | return [types.TextContent(type="text", text=str(result))]
1929 | raise ValueError(f"Tool not found: {name}")
1930 | ```
1931 | </Tab>
1932 | </Tabs>
1933 |
1934 | ## Example tool patterns
1935 |
1936 | Here are some examples of types of tools that a server could provide:
1937 |
1938 | ### System operations
1939 |
1940 | Tools that interact with the local system:
1941 |
1942 | ```typescript
1943 | {
1944 | name: "execute_command",
1945 | description: "Run a shell command",
1946 | inputSchema: {
1947 | type: "object",
1948 | properties: {
1949 | command: { type: "string" },
1950 | args: { type: "array", items: { type: "string" } }
1951 | }
1952 | }
1953 | }
1954 | ```
1955 |
1956 | ### API integrations
1957 |
1958 | Tools that wrap external APIs:
1959 |
1960 | ```typescript
1961 | {
1962 | name: "github_create_issue",
1963 | description: "Create a GitHub issue",
1964 | inputSchema: {
1965 | type: "object",
1966 | properties: {
1967 | title: { type: "string" },
1968 | body: { type: "string" },
1969 | labels: { type: "array", items: { type: "string" } }
1970 | }
1971 | }
1972 | }
1973 | ```
1974 |
1975 | ### Data processing
1976 |
1977 | Tools that transform or analyze data:
1978 |
1979 | ```typescript
1980 | {
1981 | name: "analyze_csv",
1982 | description: "Analyze a CSV file",
1983 | inputSchema: {
1984 | type: "object",
1985 | properties: {
1986 | filepath: { type: "string" },
1987 | operations: {
1988 | type: "array",
1989 | items: {
1990 | enum: ["sum", "average", "count"]
1991 | }
1992 | }
1993 | }
1994 | }
1995 | }
1996 | ```
1997 |
1998 | ## Best practices
1999 |
2000 | When implementing tools:
2001 |
2002 | 1. Provide clear, descriptive names and descriptions
2003 | 2. Use detailed JSON Schema definitions for parameters
2004 | 3. Include examples in tool descriptions to demonstrate how the model should use them
2005 | 4. Implement proper error handling and validation
2006 | 5. Use progress reporting for long operations
2007 | 6. Keep tool operations focused and atomic
2008 | 7. Document expected return value structures
2009 | 8. Implement proper timeouts
2010 | 9. Consider rate limiting for resource-intensive operations
2011 | 10. Log tool usage for debugging and monitoring
2012 |
2013 | ## Security considerations
2014 |
2015 | When exposing tools:
2016 |
2017 | ### Input validation
2018 |
2019 | * Validate all parameters against the schema
2020 | * Sanitize file paths and system commands
2021 | * Validate URLs and external identifiers
2022 | * Check parameter sizes and ranges
2023 | * Prevent command injection
2024 |
2025 | ### Access control
2026 |
2027 | * Implement authentication where needed
2028 | * Use appropriate authorization checks
2029 | * Audit tool usage
2030 | * Rate limit requests
2031 | * Monitor for abuse
2032 |
2033 | ### Error handling
2034 |
2035 | * Don't expose internal errors to clients
2036 | * Log security-relevant errors
2037 | * Handle timeouts appropriately
2038 | * Clean up resources after errors
2039 | * Validate return values
2040 |
2041 | ## Tool discovery and updates
2042 |
2043 | MCP supports dynamic tool discovery:
2044 |
2045 | 1. Clients can list available tools at any time
2046 | 2. Servers can notify clients when tools change using `notifications/tools/list_changed`
2047 | 3. Tools can be added or removed during runtime
2048 | 4. Tool definitions can be updated (though this should be done carefully)
2049 |
2050 | ## Error handling
2051 |
2052 | Tool errors should be reported within the result object, not as MCP protocol-level errors. This allows the LLM to see and potentially handle the error. When a tool encounters an error:
2053 |
2054 | 1. Set `isError` to `true` in the result
2055 | 2. Include error details in the `content` array
2056 |
2057 | Here's an example of proper error handling for tools:
2058 |
2059 | <Tabs>
2060 | <Tab title="TypeScript">
2061 | ```typescript
2062 | try {
2063 | // Tool operation
2064 | const result = performOperation();
2065 | return {
2066 | content: [
2067 | {
2068 | type: "text",
2069 | text: `Operation successful: ${result}`
2070 | }
2071 | ]
2072 | };
2073 | } catch (error) {
2074 | return {
2075 | isError: true,
2076 | content: [
2077 | {
2078 | type: "text",
2079 | text: `Error: ${error.message}`
2080 | }
2081 | ]
2082 | };
2083 | }
2084 | ```
2085 | </Tab>
2086 |
2087 | <Tab title="Python">
2088 | ```python
2089 | try:
2090 | # Tool operation
2091 | result = perform_operation()
2092 | return types.CallToolResult(
2093 | content=[
2094 | types.TextContent(
2095 | type="text",
2096 | text=f"Operation successful: {result}"
2097 | )
2098 | ]
2099 | )
2100 | except Exception as error:
2101 | return types.CallToolResult(
2102 | isError=True,
2103 | content=[
2104 | types.TextContent(
2105 | type="text",
2106 | text=f"Error: {str(error)}"
2107 | )
2108 | ]
2109 | )
2110 | ```
2111 | </Tab>
2112 | </Tabs>
2113 |
2114 | This approach allows the LLM to see that an error occurred and potentially take corrective action or request human intervention.
2115 |
2116 | ## Testing tools
2117 |
2118 | A comprehensive testing strategy for MCP tools should cover:
2119 |
2120 | * **Functional testing**: Verify tools execute correctly with valid inputs and handle invalid inputs appropriately
2121 | * **Integration testing**: Test tool interaction with external systems using both real and mocked dependencies
2122 | * **Security testing**: Validate authentication, authorization, input sanitization, and rate limiting
2123 | * **Performance testing**: Check behavior under load, timeout handling, and resource cleanup
2124 | * **Error handling**: Ensure tools properly report errors through the MCP protocol and clean up resources
2125 |
2126 |
2127 | # Transports
2128 | Source: https://modelcontextprotocol.io/docs/concepts/transports
2129 |
2130 | Learn about MCP's communication mechanisms
2131 |
2132 | Transports in the Model Context Protocol (MCP) provide the foundation for communication between clients and servers. A transport handles the underlying mechanics of how messages are sent and received.
2133 |
2134 | ## Message Format
2135 |
2136 | MCP uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 as its wire format. The transport layer is responsible for converting MCP protocol messages into JSON-RPC format for transmission and converting received JSON-RPC messages back into MCP protocol messages.
2137 |
2138 | There are three types of JSON-RPC messages used:
2139 |
2140 | ### Requests
2141 |
2142 | ```typescript
2143 | {
2144 | jsonrpc: "2.0",
2145 | id: number | string,
2146 | method: string,
2147 | params?: object
2148 | }
2149 | ```
2150 |
2151 | ### Responses
2152 |
2153 | ```typescript
2154 | {
2155 | jsonrpc: "2.0",
2156 | id: number | string,
2157 | result?: object,
2158 | error?: {
2159 | code: number,
2160 | message: string,
2161 | data?: unknown
2162 | }
2163 | }
2164 | ```
2165 |
2166 | ### Notifications
2167 |
2168 | ```typescript
2169 | {
2170 | jsonrpc: "2.0",
2171 | method: string,
2172 | params?: object
2173 | }
2174 | ```
2175 |
2176 | ## Built-in Transport Types
2177 |
2178 | MCP includes two standard transport implementations:
2179 |
2180 | ### Standard Input/Output (stdio)
2181 |
2182 | The stdio transport enables communication through standard input and output streams. This is particularly useful for local integrations and command-line tools.
2183 |
2184 | Use stdio when:
2185 |
2186 | * Building command-line tools
2187 | * Implementing local integrations
2188 | * Needing simple process communication
2189 | * Working with shell scripts
2190 |
2191 | <Tabs>
2192 | <Tab title="TypeScript (Server)">
2193 | ```typescript
2194 | const server = new Server({
2195 | name: "example-server",
2196 | version: "1.0.0"
2197 | }, {
2198 | capabilities: {}
2199 | });
2200 |
2201 | const transport = new StdioServerTransport();
2202 | await server.connect(transport);
2203 | ```
2204 | </Tab>
2205 |
2206 | <Tab title="TypeScript (Client)">
2207 | ```typescript
2208 | const client = new Client({
2209 | name: "example-client",
2210 | version: "1.0.0"
2211 | }, {
2212 | capabilities: {}
2213 | });
2214 |
2215 | const transport = new StdioClientTransport({
2216 | command: "./server",
2217 | args: ["--option", "value"]
2218 | });
2219 | await client.connect(transport);
2220 | ```
2221 | </Tab>
2222 |
2223 | <Tab title="Python (Server)">
2224 | ```python
2225 | app = Server("example-server")
2226 |
2227 | async with stdio_server() as streams:
2228 | await app.run(
2229 | streams[0],
2230 | streams[1],
2231 | app.create_initialization_options()
2232 | )
2233 | ```
2234 | </Tab>
2235 |
2236 | <Tab title="Python (Client)">
2237 | ```python
2238 | params = StdioServerParameters(
2239 | command="./server",
2240 | args=["--option", "value"]
2241 | )
2242 |
2243 | async with stdio_client(params) as streams:
2244 | async with ClientSession(streams[0], streams[1]) as session:
2245 | await session.initialize()
2246 | ```
2247 | </Tab>
2248 | </Tabs>
2249 |
2250 | ### Server-Sent Events (SSE)
2251 |
2252 | SSE transport enables server-to-client streaming with HTTP POST requests for client-to-server communication.
2253 |
2254 | Use SSE when:
2255 |
2256 | * Only server-to-client streaming is needed
2257 | * Working with restricted networks
2258 | * Implementing simple updates
2259 |
2260 | <Tabs>
2261 | <Tab title="TypeScript (Server)">
2262 | ```typescript
2263 | import express from "express";
2264 |
2265 | const app = express();
2266 |
2267 | const server = new Server({
2268 | name: "example-server",
2269 | version: "1.0.0"
2270 | }, {
2271 | capabilities: {}
2272 | });
2273 |
2274 | let transport: SSEServerTransport | null = null;
2275 |
2276 | app.get("/sse", (req, res) => {
2277 | transport = new SSEServerTransport("/messages", res);
2278 | server.connect(transport);
2279 | });
2280 |
2281 | app.post("/messages", (req, res) => {
2282 | if (transport) {
2283 | transport.handlePostMessage(req, res);
2284 | }
2285 | });
2286 |
2287 | app.listen(3000);
2288 | ```
2289 | </Tab>
2290 |
2291 | <Tab title="TypeScript (Client)">
2292 | ```typescript
2293 | const client = new Client({
2294 | name: "example-client",
2295 | version: "1.0.0"
2296 | }, {
2297 | capabilities: {}
2298 | });
2299 |
2300 | const transport = new SSEClientTransport(
2301 | new URL("http://localhost:3000/sse")
2302 | );
2303 | await client.connect(transport);
2304 | ```
2305 | </Tab>
2306 |
2307 | <Tab title="Python (Server)">
2308 | ```python
2309 | from mcp.server.sse import SseServerTransport
2310 | from starlette.applications import Starlette
2311 | from starlette.routing import Route
2312 |
2313 | app = Server("example-server")
2314 | sse = SseServerTransport("/messages")
2315 |
2316 | async def handle_sse(scope, receive, send):
2317 | async with sse.connect_sse(scope, receive, send) as streams:
2318 | await app.run(streams[0], streams[1], app.create_initialization_options())
2319 |
2320 | async def handle_messages(scope, receive, send):
2321 | await sse.handle_post_message(scope, receive, send)
2322 |
2323 | starlette_app = Starlette(
2324 | routes=[
2325 | Route("/sse", endpoint=handle_sse),
2326 | Route("/messages", endpoint=handle_messages, methods=["POST"]),
2327 | ]
2328 | )
2329 | ```
2330 | </Tab>
2331 |
2332 | <Tab title="Python (Client)">
2333 | ```python
2334 | async with sse_client("http://localhost:8000/sse") as streams:
2335 | async with ClientSession(streams[0], streams[1]) as session:
2336 | await session.initialize()
2337 | ```
2338 | </Tab>
2339 | </Tabs>
2340 |
2341 | ## Custom Transports
2342 |
2343 | MCP makes it easy to implement custom transports for specific needs. Any transport implementation just needs to conform to the Transport interface:
2344 |
2345 | You can implement custom transports for:
2346 |
2347 | * Custom network protocols
2348 | * Specialized communication channels
2349 | * Integration with existing systems
2350 | * Performance optimization
2351 |
2352 | <Tabs>
2353 | <Tab title="TypeScript">
2354 | ```typescript
2355 | interface Transport {
2356 | // Start processing messages
2357 | start(): Promise<void>;
2358 |
2359 | // Send a JSON-RPC message
2360 | send(message: JSONRPCMessage): Promise<void>;
2361 |
2362 | // Close the connection
2363 | close(): Promise<void>;
2364 |
2365 | // Callbacks
2366 | onclose?: () => void;
2367 | onerror?: (error: Error) => void;
2368 | onmessage?: (message: JSONRPCMessage) => void;
2369 | }
2370 | ```
2371 | </Tab>
2372 |
2373 | <Tab title="Python">
2374 | Note that while MCP Servers are often implemented with asyncio, we recommend
2375 | implementing low-level interfaces like transports with `anyio` for wider compatibility.
2376 |
2377 | ```python
2378 | @contextmanager
2379 | async def create_transport(
2380 | read_stream: MemoryObjectReceiveStream[JSONRPCMessage | Exception],
2381 | write_stream: MemoryObjectSendStream[JSONRPCMessage]
2382 | ):
2383 | """
2384 | Transport interface for MCP.
2385 |
2386 | Args:
2387 | read_stream: Stream to read incoming messages from
2388 | write_stream: Stream to write outgoing messages to
2389 | """
2390 | async with anyio.create_task_group() as tg:
2391 | try:
2392 | # Start processing messages
2393 | tg.start_soon(lambda: process_messages(read_stream))
2394 |
2395 | # Send messages
2396 | async with write_stream:
2397 | yield write_stream
2398 |
2399 | except Exception as exc:
2400 | # Handle errors
2401 | raise exc
2402 | finally:
2403 | # Clean up
2404 | tg.cancel_scope.cancel()
2405 | await write_stream.aclose()
2406 | await read_stream.aclose()
2407 | ```
2408 | </Tab>
2409 | </Tabs>
2410 |
2411 | ## Error Handling
2412 |
2413 | Transport implementations should handle various error scenarios:
2414 |
2415 | 1. Connection errors
2416 | 2. Message parsing errors
2417 | 3. Protocol errors
2418 | 4. Network timeouts
2419 | 5. Resource cleanup
2420 |
2421 | Example error handling:
2422 |
2423 | <Tabs>
2424 | <Tab title="TypeScript">
2425 | ```typescript
2426 | class ExampleTransport implements Transport {
2427 | async start() {
2428 | try {
2429 | // Connection logic
2430 | } catch (error) {
2431 | this.onerror?.(new Error(`Failed to connect: ${error}`));
2432 | throw error;
2433 | }
2434 | }
2435 |
2436 | async send(message: JSONRPCMessage) {
2437 | try {
2438 | // Sending logic
2439 | } catch (error) {
2440 | this.onerror?.(new Error(`Failed to send message: ${error}`));
2441 | throw error;
2442 | }
2443 | }
2444 | }
2445 | ```
2446 | </Tab>
2447 |
2448 | <Tab title="Python">
2449 | Note that while MCP Servers are often implemented with asyncio, we recommend
2450 | implementing low-level interfaces like transports with `anyio` for wider compatibility.
2451 |
2452 | ```python
2453 | @contextmanager
2454 | async def example_transport(scope: Scope, receive: Receive, send: Send):
2455 | try:
2456 | # Create streams for bidirectional communication
2457 | read_stream_writer, read_stream = anyio.create_memory_object_stream(0)
2458 | write_stream, write_stream_reader = anyio.create_memory_object_stream(0)
2459 |
2460 | async def message_handler():
2461 | try:
2462 | async with read_stream_writer:
2463 | # Message handling logic
2464 | pass
2465 | except Exception as exc:
2466 | logger.error(f"Failed to handle message: {exc}")
2467 | raise exc
2468 |
2469 | async with anyio.create_task_group() as tg:
2470 | tg.start_soon(message_handler)
2471 | try:
2472 | # Yield streams for communication
2473 | yield read_stream, write_stream
2474 | except Exception as exc:
2475 | logger.error(f"Transport error: {exc}")
2476 | raise exc
2477 | finally:
2478 | tg.cancel_scope.cancel()
2479 | await write_stream.aclose()
2480 | await read_stream.aclose()
2481 | except Exception as exc:
2482 | logger.error(f"Failed to initialize transport: {exc}")
2483 | raise exc
2484 | ```
2485 | </Tab>
2486 | </Tabs>
2487 |
2488 | ## Best Practices
2489 |
2490 | When implementing or using MCP transport:
2491 |
2492 | 1. Handle connection lifecycle properly
2493 | 2. Implement proper error handling
2494 | 3. Clean up resources on connection close
2495 | 4. Use appropriate timeouts
2496 | 5. Validate messages before sending
2497 | 6. Log transport events for debugging
2498 | 7. Implement reconnection logic when appropriate
2499 | 8. Handle backpressure in message queues
2500 | 9. Monitor connection health
2501 | 10. Implement proper security measures
2502 |
2503 | ## Security Considerations
2504 |
2505 | When implementing transport:
2506 |
2507 | ### Authentication and Authorization
2508 |
2509 | * Implement proper authentication mechanisms
2510 | * Validate client credentials
2511 | * Use secure token handling
2512 | * Implement authorization checks
2513 |
2514 | ### Data Security
2515 |
2516 | * Use TLS for network transport
2517 | * Encrypt sensitive data
2518 | * Validate message integrity
2519 | * Implement message size limits
2520 | * Sanitize input data
2521 |
2522 | ### Network Security
2523 |
2524 | * Implement rate limiting
2525 | * Use appropriate timeouts
2526 | * Handle denial of service scenarios
2527 | * Monitor for unusual patterns
2528 | * Implement proper firewall rules
2529 |
2530 | ## Debugging Transport
2531 |
2532 | Tips for debugging transport issues:
2533 |
2534 | 1. Enable debug logging
2535 | 2. Monitor message flow
2536 | 3. Check connection states
2537 | 4. Validate message formats
2538 | 5. Test error scenarios
2539 | 6. Use network analysis tools
2540 | 7. Implement health checks
2541 | 8. Monitor resource usage
2542 | 9. Test edge cases
2543 | 10. Use proper error tracking
2544 |
2545 |
2546 | # Debugging
2547 | Source: https://modelcontextprotocol.io/docs/tools/debugging
2548 |
2549 | A comprehensive guide to debugging Model Context Protocol (MCP) integrations
2550 |
2551 | Effective debugging is essential when developing MCP servers or integrating them with applications. This guide covers the debugging tools and approaches available in the MCP ecosystem.
2552 |
2553 | <Info>
2554 | This guide is for macOS. Guides for other platforms are coming soon.
2555 | </Info>
2556 |
2557 | ## Debugging tools overview
2558 |
2559 | MCP provides several tools for debugging at different levels:
2560 |
2561 | 1. **MCP Inspector**
2562 | * Interactive debugging interface
2563 | * Direct server testing
2564 | * See the [Inspector guide](/docs/tools/inspector) for details
2565 |
2566 | 2. **Claude Desktop Developer Tools**
2567 | * Integration testing
2568 | * Log collection
2569 | * Chrome DevTools integration
2570 |
2571 | 3. **Server Logging**
2572 | * Custom logging implementations
2573 | * Error tracking
2574 | * Performance monitoring
2575 |
2576 | ## Debugging in Claude Desktop
2577 |
2578 | ### Checking server status
2579 |
2580 | The Claude.app interface provides basic server status information:
2581 |
2582 | 1. Click the <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-plug-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon to view:
2583 | * Connected servers
2584 | * Available prompts and resources
2585 |
2586 | 2. Click the <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon to view:
2587 | * Tools made available to the model
2588 |
2589 | ### Viewing logs
2590 |
2591 | Review detailed MCP logs from Claude Desktop:
2592 |
2593 | ```bash
2594 | # Follow logs in real-time
2595 | tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
2596 | ```
2597 |
2598 | The logs capture:
2599 |
2600 | * Server connection events
2601 | * Configuration issues
2602 | * Runtime errors
2603 | * Message exchanges
2604 |
2605 | ### Using Chrome DevTools
2606 |
2607 | Access Chrome's developer tools inside Claude Desktop to investigate client-side errors:
2608 |
2609 | 1. Create a `developer_settings.json` file with `allowDevTools` set to true:
2610 |
2611 | ```bash
2612 | echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
2613 | ```
2614 |
2615 | 2. Open DevTools: `Command-Option-Shift-i`
2616 |
2617 | Note: You'll see two DevTools windows:
2618 |
2619 | * Main content window
2620 | * App title bar window
2621 |
2622 | Use the Console panel to inspect client-side errors.
2623 |
2624 | Use the Network panel to inspect:
2625 |
2626 | * Message payloads
2627 | * Connection timing
2628 |
2629 | ## Common issues
2630 |
2631 | ### Working directory
2632 |
2633 | When using MCP servers with Claude Desktop:
2634 |
2635 | * The working directory for servers launched via `claude_desktop_config.json` may be undefined (like `/` on macOS) since Claude Desktop could be started from anywhere
2636 | * Always use absolute paths in your configuration and `.env` files to ensure reliable operation
2637 | * For testing servers directly via command line, the working directory will be where you run the command
2638 |
2639 | For example in `claude_desktop_config.json`, use:
2640 |
2641 | ```json
2642 | {
2643 | "command": "npx",
2644 | "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
2645 | }
2646 | ```
2647 |
2648 | Instead of relative paths like `./data`
2649 |
2650 | ### Environment variables
2651 |
2652 | MCP servers inherit only a subset of environment variables automatically, like `USER`, `HOME`, and `PATH`.
2653 |
2654 | To override the default variables or provide your own, you can specify an `env` key in `claude_desktop_config.json`:
2655 |
2656 | ```json
2657 | {
2658 | "myserver": {
2659 | "command": "mcp-server-myapp",
2660 | "env": {
2661 | "MYAPP_API_KEY": "some_key",
2662 | }
2663 | }
2664 | }
2665 | ```
2666 |
2667 | ### Server initialization
2668 |
2669 | Common initialization problems:
2670 |
2671 | 1. **Path Issues**
2672 | * Incorrect server executable path
2673 | * Missing required files
2674 | * Permission problems
2675 | * Try using an absolute path for `command`
2676 |
2677 | 2. **Configuration Errors**
2678 | * Invalid JSON syntax
2679 | * Missing required fields
2680 | * Type mismatches
2681 |
2682 | 3. **Environment Problems**
2683 | * Missing environment variables
2684 | * Incorrect variable values
2685 | * Permission restrictions
2686 |
2687 | ### Connection problems
2688 |
2689 | When servers fail to connect:
2690 |
2691 | 1. Check Claude Desktop logs
2692 | 2. Verify server process is running
2693 | 3. Test standalone with [Inspector](/docs/tools/inspector)
2694 | 4. Verify protocol compatibility
2695 |
2696 | ## Implementing logging
2697 |
2698 | ### Server-side logging
2699 |
2700 | When building a server that uses the local stdio [transport](/docs/concepts/transports), all messages logged to stderr (standard error) will be captured by the host application (e.g., Claude Desktop) automatically.
2701 |
2702 | <Warning>
2703 | Local MCP servers should not log messages to stdout (standard out), as this will interfere with protocol operation.
2704 | </Warning>
2705 |
2706 | For all [transports](/docs/concepts/transports), you can also provide logging to the client by sending a log message notification:
2707 |
2708 | <Tabs>
2709 | <Tab title="Python">
2710 | ```python
2711 | server.request_context.session.send_log_message(
2712 | level="info",
2713 | data="Server started successfully",
2714 | )
2715 | ```
2716 | </Tab>
2717 |
2718 | <Tab title="TypeScript">
2719 | ```typescript
2720 | server.sendLoggingMessage({
2721 | level: "info",
2722 | data: "Server started successfully",
2723 | });
2724 | ```
2725 | </Tab>
2726 | </Tabs>
2727 |
2728 | Important events to log:
2729 |
2730 | * Initialization steps
2731 | * Resource access
2732 | * Tool execution
2733 | * Error conditions
2734 | * Performance metrics
2735 |
2736 | ### Client-side logging
2737 |
2738 | In client applications:
2739 |
2740 | 1. Enable debug logging
2741 | 2. Monitor network traffic
2742 | 3. Track message exchanges
2743 | 4. Record error states
2744 |
2745 | ## Debugging workflow
2746 |
2747 | ### Development cycle
2748 |
2749 | 1. Initial Development
2750 | * Use [Inspector](/docs/tools/inspector) for basic testing
2751 | * Implement core functionality
2752 | * Add logging points
2753 |
2754 | 2. Integration Testing
2755 | * Test in Claude Desktop
2756 | * Monitor logs
2757 | * Check error handling
2758 |
2759 | ### Testing changes
2760 |
2761 | To test changes efficiently:
2762 |
2763 | * **Configuration changes**: Restart Claude Desktop
2764 | * **Server code changes**: Use Command-R to reload
2765 | * **Quick iteration**: Use [Inspector](/docs/tools/inspector) during development
2766 |
2767 | ## Best practices
2768 |
2769 | ### Logging strategy
2770 |
2771 | 1. **Structured Logging**
2772 | * Use consistent formats
2773 | * Include context
2774 | * Add timestamps
2775 | * Track request IDs
2776 |
2777 | 2. **Error Handling**
2778 | * Log stack traces
2779 | * Include error context
2780 | * Track error patterns
2781 | * Monitor recovery
2782 |
2783 | 3. **Performance Tracking**
2784 | * Log operation timing
2785 | * Monitor resource usage
2786 | * Track message sizes
2787 | * Measure latency
2788 |
2789 | ### Security considerations
2790 |
2791 | When debugging:
2792 |
2793 | 1. **Sensitive Data**
2794 | * Sanitize logs
2795 | * Protect credentials
2796 | * Mask personal information
2797 |
2798 | 2. **Access Control**
2799 | * Verify permissions
2800 | * Check authentication
2801 | * Monitor access patterns
2802 |
2803 | ## Getting help
2804 |
2805 | When encountering issues:
2806 |
2807 | 1. **First Steps**
2808 | * Check server logs
2809 | * Test with [Inspector](/docs/tools/inspector)
2810 | * Review configuration
2811 | * Verify environment
2812 |
2813 | 2. **Support Channels**
2814 | * GitHub issues
2815 | * GitHub discussions
2816 |
2817 | 3. **Providing Information**
2818 | * Log excerpts
2819 | * Configuration files
2820 | * Steps to reproduce
2821 | * Environment details
2822 |
2823 | ## Next steps
2824 |
2825 | <CardGroup cols={2}>
2826 | <Card title="MCP Inspector" icon="magnifying-glass" href="/docs/tools/inspector">
2827 | Learn to use the MCP Inspector
2828 | </Card>
2829 | </CardGroup>
2830 |
2831 |
2832 | # Inspector
2833 | Source: https://modelcontextprotocol.io/docs/tools/inspector
2834 |
2835 | In-depth guide to using the MCP Inspector for testing and debugging Model Context Protocol servers
2836 |
2837 | The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive developer tool for testing and debugging MCP servers. While the [Debugging Guide](/docs/tools/debugging) covers the Inspector as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector's features and capabilities.
2838 |
2839 | ## Getting started
2840 |
2841 | ### Installation and basic usage
2842 |
2843 | The Inspector runs directly through `npx` without requiring installation:
2844 |
2845 | ```bash
2846 | npx @modelcontextprotocol/inspector <command>
2847 | ```
2848 |
2849 | ```bash
2850 | npx @modelcontextprotocol/inspector <command> <arg1> <arg2>
2851 | ```
2852 |
2853 | #### Inspecting servers from NPM or PyPi
2854 |
2855 | A common way to start server packages from [NPM](https://npmjs.com) or [PyPi](https://pypi.com).
2856 |
2857 | <Tabs>
2858 | <Tab title="NPM package">
2859 | ```bash
2860 | npx -y @modelcontextprotocol/inspector npx <package-name> <args>
2861 | # For example
2862 | npx -y @modelcontextprotocol/inspector npx server-postgres postgres://127.0.0.1/testdb
2863 | ```
2864 | </Tab>
2865 |
2866 | <Tab title="PyPi package">
2867 | ```bash
2868 | npx @modelcontextprotocol/inspector uvx <package-name> <args>
2869 | # For example
2870 | npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git
2871 | ```
2872 | </Tab>
2873 | </Tabs>
2874 |
2875 | #### Inspecting locally developed servers
2876 |
2877 | To inspect servers locally developed or downloaded as a repository, the most common
2878 | way is:
2879 |
2880 | <Tabs>
2881 | <Tab title="TypeScript">
2882 | ```bash
2883 | npx @modelcontextprotocol/inspector node path/to/server/index.js args...
2884 | ```
2885 | </Tab>
2886 |
2887 | <Tab title="Python">
2888 | ```bash
2889 | npx @modelcontextprotocol/inspector \
2890 | uv \
2891 | --directory path/to/server \
2892 | run \
2893 | package-name \
2894 | args...
2895 | ```
2896 | </Tab>
2897 | </Tabs>
2898 |
2899 | Please carefully read any attached README for the most accurate instructions.
2900 |
2901 | ## Feature overview
2902 |
2903 | <Frame caption="The MCP Inspector interface">
2904 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/mcp-inspector.png" />
2905 | </Frame>
2906 |
2907 | The Inspector provides several features for interacting with your MCP server:
2908 |
2909 | ### Server connection pane
2910 |
2911 | * Allows selecting the [transport](/docs/concepts/transports) for connecting to the server
2912 | * For local servers, supports customizing the command-line arguments and environment
2913 |
2914 | ### Resources tab
2915 |
2916 | * Lists all available resources
2917 | * Shows resource metadata (MIME types, descriptions)
2918 | * Allows resource content inspection
2919 | * Supports subscription testing
2920 |
2921 | ### Prompts tab
2922 |
2923 | * Displays available prompt templates
2924 | * Shows prompt arguments and descriptions
2925 | * Enables prompt testing with custom arguments
2926 | * Previews generated messages
2927 |
2928 | ### Tools tab
2929 |
2930 | * Lists available tools
2931 | * Shows tool schemas and descriptions
2932 | * Enables tool testing with custom inputs
2933 | * Displays tool execution results
2934 |
2935 | ### Notifications pane
2936 |
2937 | * Presents all logs recorded from the server
2938 | * Shows notifications received from the server
2939 |
2940 | ## Best practices
2941 |
2942 | ### Development workflow
2943 |
2944 | 1. Start Development
2945 | * Launch Inspector with your server
2946 | * Verify basic connectivity
2947 | * Check capability negotiation
2948 |
2949 | 2. Iterative testing
2950 | * Make server changes
2951 | * Rebuild the server
2952 | * Reconnect the Inspector
2953 | * Test affected features
2954 | * Monitor messages
2955 |
2956 | 3. Test edge cases
2957 | * Invalid inputs
2958 | * Missing prompt arguments
2959 | * Concurrent operations
2960 | * Verify error handling and error responses
2961 |
2962 | ## Next steps
2963 |
2964 | <CardGroup cols={2}>
2965 | <Card title="Inspector Repository" icon="github" href="https://github.com/modelcontextprotocol/inspector">
2966 | Check out the MCP Inspector source code
2967 | </Card>
2968 |
2969 | <Card title="Debugging Guide" icon="bug" href="/docs/tools/debugging">
2970 | Learn about broader debugging strategies
2971 | </Card>
2972 | </CardGroup>
2973 |
2974 |
2975 | # Example Servers
2976 | Source: https://modelcontextprotocol.io/examples
2977 |
2978 | A list of example servers and implementations
2979 |
2980 | This page showcases various Model Context Protocol (MCP) servers that demonstrate the protocol's capabilities and versatility. These servers enable Large Language Models (LLMs) to securely access tools and data sources.
2981 |
2982 | ## Reference implementations
2983 |
2984 | These official reference servers demonstrate core MCP features and SDK usage:
2985 |
2986 | ### Data and file systems
2987 |
2988 | * **[Filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)** - Secure file operations with configurable access controls
2989 | * **[PostgreSQL](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres)** - Read-only database access with schema inspection capabilities
2990 | * **[SQLite](https://github.com/modelcontextprotocol/servers/tree/main/src/sqlite)** - Database interaction and business intelligence features
2991 | * **[Google Drive](https://github.com/modelcontextprotocol/servers/tree/main/src/gdrive)** - File access and search capabilities for Google Drive
2992 |
2993 | ### Development tools
2994 |
2995 | * **[Git](https://github.com/modelcontextprotocol/servers/tree/main/src/git)** - Tools to read, search, and manipulate Git repositories
2996 | * **[GitHub](https://github.com/modelcontextprotocol/servers/tree/main/src/github)** - Repository management, file operations, and GitHub API integration
2997 | * **[GitLab](https://github.com/modelcontextprotocol/servers/tree/main/src/gitlab)** - GitLab API integration enabling project management
2998 | * **[Sentry](https://github.com/modelcontextprotocol/servers/tree/main/src/sentry)** - Retrieving and analyzing issues from Sentry.io
2999 |
3000 | ### Web and browser automation
3001 |
3002 | * **[Brave Search](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search)** - Web and local search using Brave's Search API
3003 | * **[Fetch](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch)** - Web content fetching and conversion optimized for LLM usage
3004 | * **[Puppeteer](https://github.com/modelcontextprotocol/servers/tree/main/src/puppeteer)** - Browser automation and web scraping capabilities
3005 |
3006 | ### Productivity and communication
3007 |
3008 | * **[Slack](https://github.com/modelcontextprotocol/servers/tree/main/src/slack)** - Channel management and messaging capabilities
3009 | * **[Google Maps](https://github.com/modelcontextprotocol/servers/tree/main/src/google-maps)** - Location services, directions, and place details
3010 | * **[Memory](https://github.com/modelcontextprotocol/servers/tree/main/src/memory)** - Knowledge graph-based persistent memory system
3011 |
3012 | ### AI and specialized tools
3013 |
3014 | * **[EverArt](https://github.com/modelcontextprotocol/servers/tree/main/src/everart)** - AI image generation using various models
3015 | * **[Sequential Thinking](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking)** - Dynamic problem-solving through thought sequences
3016 | * **[AWS KB Retrieval](https://github.com/modelcontextprotocol/servers/tree/main/src/aws-kb-retrieval-server)** - Retrieval from AWS Knowledge Base using Bedrock Agent Runtime
3017 |
3018 | ## Official integrations
3019 |
3020 | These MCP servers are maintained by companies for their platforms:
3021 |
3022 | * **[Axiom](https://github.com/axiomhq/mcp-server-axiom)** - Query and analyze logs, traces, and event data using natural language
3023 | * **[Browserbase](https://github.com/browserbase/mcp-server-browserbase)** - Automate browser interactions in the cloud
3024 | * **[Cloudflare](https://github.com/cloudflare/mcp-server-cloudflare)** - Deploy and manage resources on the Cloudflare developer platform
3025 | * **[E2B](https://github.com/e2b-dev/mcp-server)** - Execute code in secure cloud sandboxes
3026 | * **[Neon](https://github.com/neondatabase/mcp-server-neon)** - Interact with the Neon serverless Postgres platform
3027 | * **[Obsidian Markdown Notes](https://github.com/calclavia/mcp-obsidian)** - Read and search through Markdown notes in Obsidian vaults
3028 | * **[Qdrant](https://github.com/qdrant/mcp-server-qdrant/)** - Implement semantic memory using the Qdrant vector search engine
3029 | * **[Raygun](https://github.com/MindscapeHQ/mcp-server-raygun)** - Access crash reporting and monitoring data
3030 | * **[Search1API](https://github.com/fatwang2/search1api-mcp)** - Unified API for search, crawling, and sitemaps
3031 | * **[Stripe](https://github.com/stripe/agent-toolkit)** - Interact with the Stripe API
3032 | * **[Tinybird](https://github.com/tinybirdco/mcp-tinybird)** - Interface with the Tinybird serverless ClickHouse platform
3033 |
3034 | ## Community highlights
3035 |
3036 | A growing ecosystem of community-developed servers extends MCP's capabilities:
3037 |
3038 | * **[Docker](https://github.com/ckreiling/mcp-server-docker)** - Manage containers, images, volumes, and networks
3039 | * **[Kubernetes](https://github.com/Flux159/mcp-server-kubernetes)** - Manage pods, deployments, and services
3040 | * **[Linear](https://github.com/jerhadf/linear-mcp-server)** - Project management and issue tracking
3041 | * **[Snowflake](https://github.com/datawiz168/mcp-snowflake-service)** - Interact with Snowflake databases
3042 | * **[Spotify](https://github.com/varunneal/spotify-mcp)** - Control Spotify playback and manage playlists
3043 | * **[Todoist](https://github.com/abhiz123/todoist-mcp-server)** - Task management integration
3044 |
3045 | > **Note:** Community servers are untested and should be used at your own risk. They are not affiliated with or endorsed by Anthropic.
3046 |
3047 | For a complete list of community servers, visit the [MCP Servers Repository](https://github.com/modelcontextprotocol/servers).
3048 |
3049 | ## Getting started
3050 |
3051 | ### Using reference servers
3052 |
3053 | TypeScript-based servers can be used directly with `npx`:
3054 |
3055 | ```bash
3056 | npx -y @modelcontextprotocol/server-memory
3057 | ```
3058 |
3059 | Python-based servers can be used with `uvx` (recommended) or `pip`:
3060 |
3061 | ```bash
3062 | # Using uvx
3063 | uvx mcp-server-git
3064 |
3065 | # Using pip
3066 | pip install mcp-server-git
3067 | python -m mcp_server_git
3068 | ```
3069 |
3070 | ### Configuring with Claude
3071 |
3072 | To use an MCP server with Claude, add it to your configuration:
3073 |
3074 | ```json
3075 | {
3076 | "mcpServers": {
3077 | "memory": {
3078 | "command": "npx",
3079 | "args": ["-y", "@modelcontextprotocol/server-memory"]
3080 | },
3081 | "filesystem": {
3082 | "command": "npx",
3083 | "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
3084 | },
3085 | "github": {
3086 | "command": "npx",
3087 | "args": ["-y", "@modelcontextprotocol/server-github"],
3088 | "env": {
3089 | "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
3090 | }
3091 | }
3092 | }
3093 | }
3094 | ```
3095 |
3096 | ## Additional resources
3097 |
3098 | * [MCP Servers Repository](https://github.com/modelcontextprotocol/servers) - Complete collection of reference implementations and community servers
3099 | * [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) - Curated list of MCP servers
3100 | * [MCP CLI](https://github.com/wong2/mcp-cli) - Command-line inspector for testing MCP servers
3101 | * [MCP Get](https://mcp-get.com) - Tool for installing and managing MCP servers
3102 | * [Supergateway](https://github.com/supercorp-ai/supergateway) - Run MCP stdio servers over SSE
3103 |
3104 | Visit our [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions) to engage with the MCP community.
3105 |
3106 |
3107 | # Introduction
3108 | Source: https://modelcontextprotocol.io/introduction
3109 |
3110 | Get started with the Model Context Protocol (MCP)
3111 |
3112 | <Note>Java SDK released! Check out [what else is new.](/development/updates)</Note>
3113 |
3114 | MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.
3115 |
3116 | ## Why MCP?
3117 |
3118 | MCP helps you build agents and complex workflows on top of LLMs. LLMs frequently need to integrate with data and tools, and MCP provides:
3119 |
3120 | * A growing list of pre-built integrations that your LLM can directly plug into
3121 | * The flexibility to switch between LLM providers and vendors
3122 | * Best practices for securing your data within your infrastructure
3123 |
3124 | ### General architecture
3125 |
3126 | At its core, MCP follows a client-server architecture where a host application can connect to multiple servers:
3127 |
3128 | ```mermaid
3129 | flowchart LR
3130 | subgraph "Your Computer"
3131 | Host["Host with MCP Client\n(Claude, IDEs, Tools)"]
3132 | S1["MCP Server A"]
3133 | S2["MCP Server B"]
3134 | S3["MCP Server C"]
3135 | Host <-->|"MCP Protocol"| S1
3136 | Host <-->|"MCP Protocol"| S2
3137 | Host <-->|"MCP Protocol"| S3
3138 | S1 <--> D1[("Local\nData Source A")]
3139 | S2 <--> D2[("Local\nData Source B")]
3140 | end
3141 | subgraph "Internet"
3142 | S3 <-->|"Web APIs"| D3[("Remote\nService C")]
3143 | end
3144 | ```
3145 |
3146 | * **MCP Hosts**: Programs like Claude Desktop, IDEs, or AI tools that want to access data through MCP
3147 | * **MCP Clients**: Protocol clients that maintain 1:1 connections with servers
3148 | * **MCP Servers**: Lightweight programs that each expose specific capabilities through the standardized Model Context Protocol
3149 | * **Local Data Sources**: Your computer's files, databases, and services that MCP servers can securely access
3150 | * **Remote Services**: External systems available over the internet (e.g., through APIs) that MCP servers can connect to
3151 |
3152 | ## Get started
3153 |
3154 | Choose the path that best fits your needs:
3155 |
3156 | #### Quick Starts
3157 |
3158 | <CardGroup cols={2}>
3159 | <Card title="For Server Developers" icon="bolt" href="/quickstart/server">
3160 | Get started building your own server to use in Claude for Desktop and other clients
3161 | </Card>
3162 |
3163 | <Card title="For Client Developers" icon="bolt" href="/quickstart/client">
3164 | Get started building your own client that can integrate with all MCP servers
3165 | </Card>
3166 |
3167 | <Card title="For Claude Desktop Users" icon="bolt" href="/quickstart/user">
3168 | Get started using pre-built servers in Claude for Desktop
3169 | </Card>
3170 | </CardGroup>
3171 |
3172 | #### Examples
3173 |
3174 | <CardGroup cols={2}>
3175 | <Card title="Example Servers" icon="grid" href="/examples">
3176 | Check out our gallery of official MCP servers and implementations
3177 | </Card>
3178 |
3179 | <Card title="Example Clients" icon="cubes" href="/clients">
3180 | View the list of clients that support MCP integrations
3181 | </Card>
3182 | </CardGroup>
3183 |
3184 | ## Tutorials
3185 |
3186 | <CardGroup cols={2}>
3187 | <Card title="Building MCP with LLMs" icon="comments" href="/tutorials/building-mcp-with-llms">
3188 | Learn how to use LLMs like Claude to speed up your MCP development
3189 | </Card>
3190 |
3191 | <Card title="Debugging Guide" icon="bug" href="/docs/tools/debugging">
3192 | Learn how to effectively debug MCP servers and integrations
3193 | </Card>
3194 |
3195 | <Card title="MCP Inspector" icon="magnifying-glass" href="/docs/tools/inspector">
3196 | Test and inspect your MCP servers with our interactive debugging tool
3197 | </Card>
3198 | </CardGroup>
3199 |
3200 | ## Explore MCP
3201 |
3202 | Dive deeper into MCP's core concepts and capabilities:
3203 |
3204 | <CardGroup cols={2}>
3205 | <Card title="Core architecture" icon="sitemap" href="/docs/concepts/architecture">
3206 | Understand how MCP connects clients, servers, and LLMs
3207 | </Card>
3208 |
3209 | <Card title="Resources" icon="database" href="/docs/concepts/resources">
3210 | Expose data and content from your servers to LLMs
3211 | </Card>
3212 |
3213 | <Card title="Prompts" icon="message" href="/docs/concepts/prompts">
3214 | Create reusable prompt templates and workflows
3215 | </Card>
3216 |
3217 | <Card title="Tools" icon="wrench" href="/docs/concepts/tools">
3218 | Enable LLMs to perform actions through your server
3219 | </Card>
3220 |
3221 | <Card title="Sampling" icon="robot" href="/docs/concepts/sampling">
3222 | Let your servers request completions from LLMs
3223 | </Card>
3224 |
3225 | <Card title="Transports" icon="network-wired" href="/docs/concepts/transports">
3226 | Learn about MCP's communication mechanism
3227 | </Card>
3228 | </CardGroup>
3229 |
3230 | ## Contributing
3231 |
3232 | Want to contribute? Check out our [Contributing Guide](/development/contributing) to learn how you can help improve MCP.
3233 |
3234 | ## Support and Feedback
3235 |
3236 | Here's how to get help or provide feedback:
3237 |
3238 | * For bug reports and feature requests related to the MCP specification, SDKs, or documentation (open source), please [create a GitHub issue](https://github.com/modelcontextprotocol)
3239 | * For discussions or Q\&A about the MCP specification, use the [specification discussions](https://github.com/modelcontextprotocol/specification/discussions)
3240 | * For discussions or Q\&A about other MCP open source components, use the [organization discussions](https://github.com/orgs/modelcontextprotocol/discussions)
3241 | * For bug reports, feature requests, and questions related to Claude.app and claude.ai's MCP integration, please email [[email protected]](mailto:[email protected])
3242 |
3243 |
3244 | # For Client Developers
3245 | Source: https://modelcontextprotocol.io/quickstart/client
3246 |
3247 | Get started building your own client that can integrate with all MCP servers.
3248 |
3249 | In this tutorial, you'll learn how to build a LLM-powered chatbot client that connects to MCP servers. It helps to have gone through the [Server quickstart](/quickstart/server) that guides you through the basic of building your first server.
3250 |
3251 | <Tabs>
3252 | <Tab title="Python">
3253 | [You can find the complete code for this tutorial here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client-python)
3254 |
3255 | ## System Requirements
3256 |
3257 | Before starting, ensure your system meets these requirements:
3258 |
3259 | * Mac or Windows computer
3260 | * Latest Python version installed
3261 | * Latest version of `uv` installed
3262 |
3263 | ## Setting Up Your Environment
3264 |
3265 | First, create a new Python project with `uv`:
3266 |
3267 | ```bash
3268 | # Create project directory
3269 | uv init mcp-client
3270 | cd mcp-client
3271 |
3272 | # Create virtual environment
3273 | uv venv
3274 |
3275 | # Activate virtual environment
3276 | # On Windows:
3277 | .venv\Scripts\activate
3278 | # On Unix or MacOS:
3279 | source .venv/bin/activate
3280 |
3281 | # Install required packages
3282 | uv add mcp anthropic python-dotenv
3283 |
3284 | # Remove boilerplate files
3285 | rm hello.py
3286 |
3287 | # Create our main file
3288 | touch client.py
3289 | ```
3290 |
3291 | ## Setting Up Your API Key
3292 |
3293 | You'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/settings/keys).
3294 |
3295 | Create a `.env` file to store it:
3296 |
3297 | ```bash
3298 | # Create .env file
3299 | touch .env
3300 | ```
3301 |
3302 | Add your key to the `.env` file:
3303 |
3304 | ```bash
3305 | ANTHROPIC_API_KEY=<your key here>
3306 | ```
3307 |
3308 | Add `.env` to your `.gitignore`:
3309 |
3310 | ```bash
3311 | echo ".env" >> .gitignore
3312 | ```
3313 |
3314 | <Warning>
3315 | Make sure you keep your `ANTHROPIC_API_KEY` secure!
3316 | </Warning>
3317 |
3318 | ## Creating the Client
3319 |
3320 | ### Basic Client Structure
3321 |
3322 | First, let's set up our imports and create the basic client class:
3323 |
3324 | ```python
3325 | import asyncio
3326 | from typing import Optional
3327 | from contextlib import AsyncExitStack
3328 |
3329 | from mcp import ClientSession, StdioServerParameters
3330 | from mcp.client.stdio import stdio_client
3331 |
3332 | from anthropic import Anthropic
3333 | from dotenv import load_dotenv
3334 |
3335 | load_dotenv() # load environment variables from .env
3336 |
3337 | class MCPClient:
3338 | def __init__(self):
3339 | # Initialize session and client objects
3340 | self.session: Optional[ClientSession] = None
3341 | self.exit_stack = AsyncExitStack()
3342 | self.anthropic = Anthropic()
3343 | # methods will go here
3344 | ```
3345 |
3346 | ### Server Connection Management
3347 |
3348 | Next, we'll implement the method to connect to an MCP server:
3349 |
3350 | ```python
3351 | async def connect_to_server(self, server_script_path: str):
3352 | """Connect to an MCP server
3353 |
3354 | Args:
3355 | server_script_path: Path to the server script (.py or .js)
3356 | """
3357 | is_python = server_script_path.endswith('.py')
3358 | is_js = server_script_path.endswith('.js')
3359 | if not (is_python or is_js):
3360 | raise ValueError("Server script must be a .py or .js file")
3361 |
3362 | command = "python" if is_python else "node"
3363 | server_params = StdioServerParameters(
3364 | command=command,
3365 | args=[server_script_path],
3366 | env=None
3367 | )
3368 |
3369 | stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
3370 | self.stdio, self.write = stdio_transport
3371 | self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))
3372 |
3373 | await self.session.initialize()
3374 |
3375 | # List available tools
3376 | response = await self.session.list_tools()
3377 | tools = response.tools
3378 | print("\nConnected to server with tools:", [tool.name for tool in tools])
3379 | ```
3380 |
3381 | ### Query Processing Logic
3382 |
3383 | Now let's add the core functionality for processing queries and handling tool calls:
3384 |
3385 | ```python
3386 | async def process_query(self, query: str) -> str:
3387 | """Process a query using Claude and available tools"""
3388 | messages = [
3389 | {
3390 | "role": "user",
3391 | "content": query
3392 | }
3393 | ]
3394 |
3395 | response = await self.session.list_tools()
3396 | available_tools = [{
3397 | "name": tool.name,
3398 | "description": tool.description,
3399 | "input_schema": tool.inputSchema
3400 | } for tool in response.tools]
3401 |
3402 | # Initial Claude API call
3403 | response = self.anthropic.messages.create(
3404 | model="claude-3-5-sonnet-20241022",
3405 | max_tokens=1000,
3406 | messages=messages,
3407 | tools=available_tools
3408 | )
3409 |
3410 | # Process response and handle tool calls
3411 | final_text = []
3412 |
3413 | assistant_message_content = []
3414 | for content in response.content:
3415 | if content.type == 'text':
3416 | final_text.append(content.text)
3417 | assistant_message_content.append(content)
3418 | elif content.type == 'tool_use':
3419 | tool_name = content.name
3420 | tool_args = content.input
3421 |
3422 | # Execute tool call
3423 | result = await self.session.call_tool(tool_name, tool_args)
3424 | final_text.append(f"[Calling tool {tool_name} with args {tool_args}]")
3425 |
3426 | assistant_message_content.append(content)
3427 | messages.append({
3428 | "role": "assistant",
3429 | "content": assistant_message_content
3430 | })
3431 | messages.append({
3432 | "role": "user",
3433 | "content": [
3434 | {
3435 | "type": "tool_result",
3436 | "tool_use_id": content.id,
3437 | "content": result.content
3438 | }
3439 | ]
3440 | })
3441 |
3442 | # Get next response from Claude
3443 | response = self.anthropic.messages.create(
3444 | model="claude-3-5-sonnet-20241022",
3445 | max_tokens=1000,
3446 | messages=messages,
3447 | tools=available_tools
3448 | )
3449 |
3450 | final_text.append(response.content[0].text)
3451 |
3452 | return "\n".join(final_text)
3453 | ```
3454 |
3455 | ### Interactive Chat Interface
3456 |
3457 | Now we'll add the chat loop and cleanup functionality:
3458 |
3459 | ```python
3460 | async def chat_loop(self):
3461 | """Run an interactive chat loop"""
3462 | print("\nMCP Client Started!")
3463 | print("Type your queries or 'quit' to exit.")
3464 |
3465 | while True:
3466 | try:
3467 | query = input("\nQuery: ").strip()
3468 |
3469 | if query.lower() == 'quit':
3470 | break
3471 |
3472 | response = await self.process_query(query)
3473 | print("\n" + response)
3474 |
3475 | except Exception as e:
3476 | print(f"\nError: {str(e)}")
3477 |
3478 | async def cleanup(self):
3479 | """Clean up resources"""
3480 | await self.exit_stack.aclose()
3481 | ```
3482 |
3483 | ### Main Entry Point
3484 |
3485 | Finally, we'll add the main execution logic:
3486 |
3487 | ```python
3488 | async def main():
3489 | if len(sys.argv) < 2:
3490 | print("Usage: python client.py <path_to_server_script>")
3491 | sys.exit(1)
3492 |
3493 | client = MCPClient()
3494 | try:
3495 | await client.connect_to_server(sys.argv[1])
3496 | await client.chat_loop()
3497 | finally:
3498 | await client.cleanup()
3499 |
3500 | if __name__ == "__main__":
3501 | import sys
3502 | asyncio.run(main())
3503 | ```
3504 |
3505 | You can find the complete `client.py` file [here.](https://gist.github.com/zckly/f3f28ea731e096e53b39b47bf0a2d4b1)
3506 |
3507 | ## Key Components Explained
3508 |
3509 | ### 1. Client Initialization
3510 |
3511 | * The `MCPClient` class initializes with session management and API clients
3512 | * Uses `AsyncExitStack` for proper resource management
3513 | * Configures the Anthropic client for Claude interactions
3514 |
3515 | ### 2. Server Connection
3516 |
3517 | * Supports both Python and Node.js servers
3518 | * Validates server script type
3519 | * Sets up proper communication channels
3520 | * Initializes the session and lists available tools
3521 |
3522 | ### 3. Query Processing
3523 |
3524 | * Maintains conversation context
3525 | * Handles Claude's responses and tool calls
3526 | * Manages the message flow between Claude and tools
3527 | * Combines results into a coherent response
3528 |
3529 | ### 4. Interactive Interface
3530 |
3531 | * Provides a simple command-line interface
3532 | * Handles user input and displays responses
3533 | * Includes basic error handling
3534 | * Allows graceful exit
3535 |
3536 | ### 5. Resource Management
3537 |
3538 | * Proper cleanup of resources
3539 | * Error handling for connection issues
3540 | * Graceful shutdown procedures
3541 |
3542 | ## Common Customization Points
3543 |
3544 | 1. **Tool Handling**
3545 | * Modify `process_query()` to handle specific tool types
3546 | * Add custom error handling for tool calls
3547 | * Implement tool-specific response formatting
3548 |
3549 | 2. **Response Processing**
3550 | * Customize how tool results are formatted
3551 | * Add response filtering or transformation
3552 | * Implement custom logging
3553 |
3554 | 3. **User Interface**
3555 | * Add a GUI or web interface
3556 | * Implement rich console output
3557 | * Add command history or auto-completion
3558 |
3559 | ## Running the Client
3560 |
3561 | To run your client with any MCP server:
3562 |
3563 | ```bash
3564 | uv run client.py path/to/server.py # python server
3565 | uv run client.py path/to/build/index.js # node server
3566 | ```
3567 |
3568 | <Note>
3569 | If you're continuing the weather tutorial from the server quickstart, your command might look something like this: `python client.py .../weather/src/weather/server.py`
3570 | </Note>
3571 |
3572 | The client will:
3573 |
3574 | 1. Connect to the specified server
3575 | 2. List available tools
3576 | 3. Start an interactive chat session where you can:
3577 | * Enter queries
3578 | * See tool executions
3579 | * Get responses from Claude
3580 |
3581 | Here's an example of what it should look like if connected to the weather server from the server quickstart:
3582 |
3583 | <Frame>
3584 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/client-claude-cli-python.png" />
3585 | </Frame>
3586 |
3587 | ## How It Works
3588 |
3589 | When you submit a query:
3590 |
3591 | 1. The client gets the list of available tools from the server
3592 | 2. Your query is sent to Claude along with tool descriptions
3593 | 3. Claude decides which tools (if any) to use
3594 | 4. The client executes any requested tool calls through the server
3595 | 5. Results are sent back to Claude
3596 | 6. Claude provides a natural language response
3597 | 7. The response is displayed to you
3598 |
3599 | ## Best practices
3600 |
3601 | 1. **Error Handling**
3602 | * Always wrap tool calls in try-catch blocks
3603 | * Provide meaningful error messages
3604 | * Gracefully handle connection issues
3605 |
3606 | 2. **Resource Management**
3607 | * Use `AsyncExitStack` for proper cleanup
3608 | * Close connections when done
3609 | * Handle server disconnections
3610 |
3611 | 3. **Security**
3612 | * Store API keys securely in `.env`
3613 | * Validate server responses
3614 | * Be cautious with tool permissions
3615 |
3616 | ## Troubleshooting
3617 |
3618 | ### Server Path Issues
3619 |
3620 | * Double-check the path to your server script is correct
3621 | * Use the absolute path if the relative path isn't working
3622 | * For Windows users, make sure to use forward slashes (/) or escaped backslashes (\\) in the path
3623 | * Verify the server file has the correct extension (.py for Python or .js for Node.js)
3624 |
3625 | Example of correct path usage:
3626 |
3627 | ```bash
3628 | # Relative path
3629 | uv run client.py ./server/weather.py
3630 |
3631 | # Absolute path
3632 | uv run client.py /Users/username/projects/mcp-server/weather.py
3633 |
3634 | # Windows path (either format works)
3635 | uv run client.py C:/projects/mcp-server/weather.py
3636 | uv run client.py C:\\projects\\mcp-server\\weather.py
3637 | ```
3638 |
3639 | ### Response Timing
3640 |
3641 | * The first response might take up to 30 seconds to return
3642 | * This is normal and happens while:
3643 | * The server initializes
3644 | * Claude processes the query
3645 | * Tools are being executed
3646 | * Subsequent responses are typically faster
3647 | * Don't interrupt the process during this initial waiting period
3648 |
3649 | ### Common Error Messages
3650 |
3651 | If you see:
3652 |
3653 | * `FileNotFoundError`: Check your server path
3654 | * `Connection refused`: Ensure the server is running and the path is correct
3655 | * `Tool execution failed`: Verify the tool's required environment variables are set
3656 | * `Timeout error`: Consider increasing the timeout in your client configuration
3657 | </Tab>
3658 |
3659 | <Tab title="Node">
3660 | [You can find the complete code for this tutorial here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client-typescript)
3661 |
3662 | ## System Requirements
3663 |
3664 | Before starting, ensure your system meets these requirements:
3665 |
3666 | * Mac or Windows computer
3667 | * Node.js 16 or higher installed
3668 | * Latest version of `npm` installed
3669 | * Anthropic API key (Claude)
3670 |
3671 | ## Setting Up Your Environment
3672 |
3673 | First, let's create and set up our project:
3674 |
3675 | <CodeGroup>
3676 | ```bash MacOS/Linux
3677 | # Create project directory
3678 | mkdir mcp-client-typescript
3679 | cd mcp-client-typescript
3680 |
3681 | # Initialize npm project
3682 | npm init -y
3683 |
3684 | # Install dependencies
3685 | npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv
3686 |
3687 | # Install dev dependencies
3688 | npm install -D @types/node typescript
3689 |
3690 | # Create source file
3691 | touch index.ts
3692 | ```
3693 |
3694 | ```powershell Windows
3695 | # Create project directory
3696 | md mcp-client-typescript
3697 | cd mcp-client-typescript
3698 |
3699 | # Initialize npm project
3700 | npm init -y
3701 |
3702 | # Install dependencies
3703 | npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv
3704 |
3705 | # Install dev dependencies
3706 | npm install -D @types/node typescript
3707 |
3708 | # Create source file
3709 | new-item index.ts
3710 | ```
3711 | </CodeGroup>
3712 |
3713 | Update your `package.json` to set `type: "module"` and a build script:
3714 |
3715 | ```json package.json
3716 | {
3717 | "type": "module",
3718 | "scripts": {
3719 | "build": "tsc && chmod 755 build/index.js"
3720 | }
3721 | }
3722 | ```
3723 |
3724 | Create a `tsconfig.json` in the root of your project:
3725 |
3726 | ```json tsconfig.json
3727 | {
3728 | "compilerOptions": {
3729 | "target": "ES2022",
3730 | "module": "Node16",
3731 | "moduleResolution": "Node16",
3732 | "outDir": "./build",
3733 | "rootDir": "./",
3734 | "strict": true,
3735 | "esModuleInterop": true,
3736 | "skipLibCheck": true,
3737 | "forceConsistentCasingInFileNames": true
3738 | },
3739 | "include": ["index.ts"],
3740 | "exclude": ["node_modules"]
3741 | }
3742 | ```
3743 |
3744 | ## Setting Up Your API Key
3745 |
3746 | You'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/settings/keys).
3747 |
3748 | Create a `.env` file to store it:
3749 |
3750 | ```bash
3751 | echo "ANTHROPIC_API_KEY=<your key here>" > .env
3752 | ```
3753 |
3754 | Add `.env` to your `.gitignore`:
3755 |
3756 | ```bash
3757 | echo ".env" >> .gitignore
3758 | ```
3759 |
3760 | <Warning>
3761 | Make sure you keep your `ANTHROPIC_API_KEY` secure!
3762 | </Warning>
3763 |
3764 | ## Creating the Client
3765 |
3766 | ### Basic Client Structure
3767 |
3768 | First, let's set up our imports and create the basic client class in `index.ts`:
3769 |
3770 | ```typescript
3771 | import { Anthropic } from "@anthropic-ai/sdk";
3772 | import {
3773 | MessageParam,
3774 | Tool,
3775 | } from "@anthropic-ai/sdk/resources/messages/messages.mjs";
3776 | import { Client } from "@modelcontextprotocol/sdk/client/index.js";
3777 | import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
3778 | import readline from "readline/promises";
3779 | import dotenv from "dotenv";
3780 |
3781 | dotenv.config();
3782 |
3783 | const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
3784 | if (!ANTHROPIC_API_KEY) {
3785 | throw new Error("ANTHROPIC_API_KEY is not set");
3786 | }
3787 |
3788 | class MCPClient {
3789 | private mcp: Client;
3790 | private anthropic: Anthropic;
3791 | private transport: StdioClientTransport | null = null;
3792 | private tools: Tool[] = [];
3793 |
3794 | constructor() {
3795 | this.anthropic = new Anthropic({
3796 | apiKey: ANTHROPIC_API_KEY,
3797 | });
3798 | this.mcp = new Client({ name: "mcp-client-cli", version: "1.0.0" });
3799 | }
3800 | // methods will go here
3801 | }
3802 | ```
3803 |
3804 | ### Server Connection Management
3805 |
3806 | Next, we'll implement the method to connect to an MCP server:
3807 |
3808 | ```typescript
3809 | async connectToServer(serverScriptPath: string) {
3810 | try {
3811 | const isJs = serverScriptPath.endsWith(".js");
3812 | const isPy = serverScriptPath.endsWith(".py");
3813 | if (!isJs && !isPy) {
3814 | throw new Error("Server script must be a .js or .py file");
3815 | }
3816 | const command = isPy
3817 | ? process.platform === "win32"
3818 | ? "python"
3819 | : "python3"
3820 | : process.execPath;
3821 |
3822 | this.transport = new StdioClientTransport({
3823 | command,
3824 | args: [serverScriptPath],
3825 | });
3826 | this.mcp.connect(this.transport);
3827 |
3828 | const toolsResult = await this.mcp.listTools();
3829 | this.tools = toolsResult.tools.map((tool) => {
3830 | return {
3831 | name: tool.name,
3832 | description: tool.description,
3833 | input_schema: tool.inputSchema,
3834 | };
3835 | });
3836 | console.log(
3837 | "Connected to server with tools:",
3838 | this.tools.map(({ name }) => name)
3839 | );
3840 | } catch (e) {
3841 | console.log("Failed to connect to MCP server: ", e);
3842 | throw e;
3843 | }
3844 | }
3845 | ```
3846 |
3847 | ### Query Processing Logic
3848 |
3849 | Now let's add the core functionality for processing queries and handling tool calls:
3850 |
3851 | ```typescript
3852 | async processQuery(query: string) {
3853 | const messages: MessageParam[] = [
3854 | {
3855 | role: "user",
3856 | content: query,
3857 | },
3858 | ];
3859 |
3860 | const response = await this.anthropic.messages.create({
3861 | model: "claude-3-5-sonnet-20241022",
3862 | max_tokens: 1000,
3863 | messages,
3864 | tools: this.tools,
3865 | });
3866 |
3867 | const finalText = [];
3868 | const toolResults = [];
3869 |
3870 | for (const content of response.content) {
3871 | if (content.type === "text") {
3872 | finalText.push(content.text);
3873 | } else if (content.type === "tool_use") {
3874 | const toolName = content.name;
3875 | const toolArgs = content.input as { [x: string]: unknown } | undefined;
3876 |
3877 | const result = await this.mcp.callTool({
3878 | name: toolName,
3879 | arguments: toolArgs,
3880 | });
3881 | toolResults.push(result);
3882 | finalText.push(
3883 | `[Calling tool ${toolName} with args ${JSON.stringify(toolArgs)}]`
3884 | );
3885 |
3886 | messages.push({
3887 | role: "user",
3888 | content: result.content as string,
3889 | });
3890 |
3891 | const response = await this.anthropic.messages.create({
3892 | model: "claude-3-5-sonnet-20241022",
3893 | max_tokens: 1000,
3894 | messages,
3895 | });
3896 |
3897 | finalText.push(
3898 | response.content[0].type === "text" ? response.content[0].text : ""
3899 | );
3900 | }
3901 | }
3902 |
3903 | return finalText.join("\n");
3904 | }
3905 | ```
3906 |
3907 | ### Interactive Chat Interface
3908 |
3909 | Now we'll add the chat loop and cleanup functionality:
3910 |
3911 | ```typescript
3912 | async chatLoop() {
3913 | const rl = readline.createInterface({
3914 | input: process.stdin,
3915 | output: process.stdout,
3916 | });
3917 |
3918 | try {
3919 | console.log("\nMCP Client Started!");
3920 | console.log("Type your queries or 'quit' to exit.");
3921 |
3922 | while (true) {
3923 | const message = await rl.question("\nQuery: ");
3924 | if (message.toLowerCase() === "quit") {
3925 | break;
3926 | }
3927 | const response = await this.processQuery(message);
3928 | console.log("\n" + response);
3929 | }
3930 | } finally {
3931 | rl.close();
3932 | }
3933 | }
3934 |
3935 | async cleanup() {
3936 | await this.mcp.close();
3937 | }
3938 | ```
3939 |
3940 | ### Main Entry Point
3941 |
3942 | Finally, we'll add the main execution logic:
3943 |
3944 | ```typescript
3945 | async function main() {
3946 | if (process.argv.length < 3) {
3947 | console.log("Usage: node index.ts <path_to_server_script>");
3948 | return;
3949 | }
3950 | const mcpClient = new MCPClient();
3951 | try {
3952 | await mcpClient.connectToServer(process.argv[2]);
3953 | await mcpClient.chatLoop();
3954 | } finally {
3955 | await mcpClient.cleanup();
3956 | process.exit(0);
3957 | }
3958 | }
3959 |
3960 | main();
3961 | ```
3962 |
3963 | ## Running the Client
3964 |
3965 | To run your client with any MCP server:
3966 |
3967 | ```bash
3968 | # Build TypeScript
3969 | npm run build
3970 |
3971 | # Run the client
3972 | node build/index.js path/to/server.py # python server
3973 | node build/index.js path/to/build/index.js # node server
3974 | ```
3975 |
3976 | <Note>
3977 | If you're continuing the weather tutorial from the server quickstart, your command might look something like this: `node build/index.js .../quickstart-resources/weather-server-typescript/build/index.js`
3978 | </Note>
3979 |
3980 | **The client will:**
3981 |
3982 | 1. Connect to the specified server
3983 | 2. List available tools
3984 | 3. Start an interactive chat session where you can:
3985 | * Enter queries
3986 | * See tool executions
3987 | * Get responses from Claude
3988 |
3989 | ## How It Works
3990 |
3991 | When you submit a query:
3992 |
3993 | 1. The client gets the list of available tools from the server
3994 | 2. Your query is sent to Claude along with tool descriptions
3995 | 3. Claude decides which tools (if any) to use
3996 | 4. The client executes any requested tool calls through the server
3997 | 5. Results are sent back to Claude
3998 | 6. Claude provides a natural language response
3999 | 7. The response is displayed to you
4000 |
4001 | ## Best practices
4002 |
4003 | 1. **Error Handling**
4004 | * Use TypeScript's type system for better error detection
4005 | * Wrap tool calls in try-catch blocks
4006 | * Provide meaningful error messages
4007 | * Gracefully handle connection issues
4008 |
4009 | 2. **Security**
4010 | * Store API keys securely in `.env`
4011 | * Validate server responses
4012 | * Be cautious with tool permissions
4013 |
4014 | ## Troubleshooting
4015 |
4016 | ### Server Path Issues
4017 |
4018 | * Double-check the path to your server script is correct
4019 | * Use the absolute path if the relative path isn't working
4020 | * For Windows users, make sure to use forward slashes (/) or escaped backslashes (\\) in the path
4021 | * Verify the server file has the correct extension (.js for Node.js or .py for Python)
4022 |
4023 | Example of correct path usage:
4024 |
4025 | ```bash
4026 | # Relative path
4027 | node build/index.js ./server/build/index.js
4028 |
4029 | # Absolute path
4030 | node build/index.js /Users/username/projects/mcp-server/build/index.js
4031 |
4032 | # Windows path (either format works)
4033 | node build/index.js C:/projects/mcp-server/build/index.js
4034 | node build/index.js C:\\projects\\mcp-server\\build\\index.js
4035 | ```
4036 |
4037 | ### Response Timing
4038 |
4039 | * The first response might take up to 30 seconds to return
4040 | * This is normal and happens while:
4041 | * The server initializes
4042 | * Claude processes the query
4043 | * Tools are being executed
4044 | * Subsequent responses are typically faster
4045 | * Don't interrupt the process during this initial waiting period
4046 |
4047 | ### Common Error Messages
4048 |
4049 | If you see:
4050 |
4051 | * `Error: Cannot find module`: Check your build folder and ensure TypeScript compilation succeeded
4052 | * `Connection refused`: Ensure the server is running and the path is correct
4053 | * `Tool execution failed`: Verify the tool's required environment variables are set
4054 | * `ANTHROPIC_API_KEY is not set`: Check your .env file and environment variables
4055 | * `TypeError`: Ensure you're using the correct types for tool arguments
4056 | </Tab>
4057 |
4058 | <Tab title="Java">
4059 | <Note>
4060 | This is a quickstart demo based on Spring AI MCP auto-configuration and boot starters.
4061 | To learn how to create sync and async MCP Clients manually, consult the [Java SDK Client](/sdk/java/mcp-client) documentation
4062 | </Note>
4063 |
4064 | This example demonstrates how to build an interactive chatbot that combines Spring AI's Model Context Protocol (MCP) with the [Brave Search MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search). The application creates a conversational interface powered by Anthropic's Claude AI model that can perform internet searches through Brave Search, enabling natural language interactions with real-time web data.
4065 | [You can find the complete code for this tutorial here.](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/web-search/brave-chatbot)
4066 |
4067 | ## System Requirements
4068 |
4069 | Before starting, ensure your system meets these requirements:
4070 |
4071 | * Java 17 or higher
4072 | * Maven 3.6+
4073 | * npx package manager
4074 | * Anthropic API key (Claude)
4075 | * Brave Search API key
4076 |
4077 | ## Setting Up Your Environment
4078 |
4079 | 1. Install npx (Node Package eXecute):
4080 | First, make sure to install [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
4081 | and then run:
4082 | ```bash
4083 | npm install -g npx
4084 | ```
4085 |
4086 | 2. Clone the repository:
4087 | ```bash
4088 | git clone https://github.com/spring-projects/spring-ai-examples.git
4089 | cd model-context-protocol/brave-chatbot
4090 | ```
4091 |
4092 | 3. Set up your API keys:
4093 | ```bash
4094 | export ANTHROPIC_API_KEY='your-anthropic-api-key-here'
4095 | export BRAVE_API_KEY='your-brave-api-key-here'
4096 | ```
4097 |
4098 | 4. Build the application:
4099 | ```bash
4100 | ./mvnw clean install
4101 | ```
4102 |
4103 | 5. Run the application using Maven:
4104 | ```bash
4105 | ./mvnw spring-boot:run
4106 | ```
4107 |
4108 | <Warning>
4109 | Make sure you keep your `ANTHROPIC_API_KEY` and `BRAVE_API_KEY` keys secure!
4110 | </Warning>
4111 |
4112 | ## How it Works
4113 |
4114 | The application integrates Spring AI with the Brave Search MCP server through several components:
4115 |
4116 | ### MCP Client Configuration
4117 |
4118 | 1. Required dependencies in pom.xml:
4119 |
4120 | ```xml
4121 | <dependency>
4122 | <groupId>org.springframework.ai</groupId>
4123 | <artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
4124 | </dependency>
4125 | <dependency>
4126 | <groupId>org.springframework.ai</groupId>
4127 | <artifactId>spring-ai-anthropic-spring-boot-starter</artifactId>
4128 | </dependency>
4129 | ```
4130 |
4131 | 2. Application properties (application.yml):
4132 |
4133 | ```yml
4134 | spring:
4135 | ai:
4136 | mcp:
4137 | client:
4138 | enabled: true
4139 | name: brave-search-client
4140 | version: 1.0.0
4141 | type: SYNC
4142 | request-timeout: 20s
4143 | stdio:
4144 | root-change-notification: true
4145 | servers-configuration: classpath:/mcp-servers-config.json
4146 | anthropic:
4147 | api-key: ${ANTHROPIC_API_KEY}
4148 | ```
4149 |
4150 | This activates the `spring-ai-mcp-client-spring-boot-starter` to create one or more `McpClient`s based on the provided server configuration.
4151 |
4152 | 3. MCP Server Configuration (`mcp-servers-config.json`):
4153 |
4154 | ```json
4155 | {
4156 | "mcpServers": {
4157 | "brave-search": {
4158 | "command": "npx",
4159 | "args": [
4160 | "-y",
4161 | "@modelcontextprotocol/server-brave-search"
4162 | ],
4163 | "env": {
4164 | "BRAVE_API_KEY": "<PUT YOUR BRAVE API KEY>"
4165 | }
4166 | }
4167 | }
4168 | }
4169 | ```
4170 |
4171 | ### Chat Implementation
4172 |
4173 | The chatbot is implemented using Spring AI's ChatClient with MCP tool integration:
4174 |
4175 | ```java
4176 | var chatClient = chatClientBuilder
4177 | .defaultSystem("You are useful assistant, expert in AI and Java.")
4178 | .defaultTools((Object[]) mcpToolAdapter.toolCallbacks())
4179 | .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
4180 | .build();
4181 | ```
4182 |
4183 | Key features:
4184 |
4185 | * Uses Claude AI model for natural language understanding
4186 | * Integrates Brave Search through MCP for real-time web search capabilities
4187 | * Maintains conversation memory using InMemoryChatMemory
4188 | * Runs as an interactive command-line application
4189 |
4190 | ### Build and run
4191 |
4192 | ```bash
4193 | ./mvnw clean install
4194 | java -jar ./target/ai-mcp-brave-chatbot-0.0.1-SNAPSHOT.jar
4195 | ```
4196 |
4197 | or
4198 |
4199 | ```bash
4200 | ./mvnw spring-boot:run
4201 | ```
4202 |
4203 | The application will start an interactive chat session where you can ask questions. The chatbot will use Brave Search when it needs to find information from the internet to answer your queries.
4204 |
4205 | The chatbot can:
4206 |
4207 | * Answer questions using its built-in knowledge
4208 | * Perform web searches when needed using Brave Search
4209 | * Remember context from previous messages in the conversation
4210 | * Combine information from multiple sources to provide comprehensive answers
4211 |
4212 | ### Advanced Configuration
4213 |
4214 | The MCP client supports additional configuration options:
4215 |
4216 | * Client customization through `McpSyncClientCustomizer` or `McpAsyncClientCustomizer`
4217 | * Multiple clients with multiple transport types: `STDIO` and `SSE` (Server-Sent Events)
4218 | * Integration with Spring AI's tool execution framework
4219 | * Automatic client initialization and lifecycle management
4220 |
4221 | For WebFlux-based applications, you can use the WebFlux starter instead:
4222 |
4223 | ```xml
4224 | <dependency>
4225 | <groupId>org.springframework.ai</groupId>
4226 | <artifactId>spring-ai-mcp-client-webflux-spring-boot-starter</artifactId>
4227 | </dependency>
4228 | ```
4229 |
4230 | This provides similar functionality but uses a WebFlux-based SSE transport implementation, recommended for production deployments.
4231 | </Tab>
4232 | </Tabs>
4233 |
4234 | ## Next steps
4235 |
4236 | <CardGroup cols={2}>
4237 | <Card title="Example servers" icon="grid" href="/examples">
4238 | Check out our gallery of official MCP servers and implementations
4239 | </Card>
4240 |
4241 | <Card title="Clients" icon="cubes" href="/clients">
4242 | View the list of clients that support MCP integrations
4243 | </Card>
4244 |
4245 | <Card title="Building MCP with LLMs" icon="comments" href="/tutorials/building-mcp-with-llms">
4246 | Learn how to use LLMs like Claude to speed up your MCP development
4247 | </Card>
4248 |
4249 | <Card title="Core architecture" icon="sitemap" href="/docs/concepts/architecture">
4250 | Understand how MCP connects clients, servers, and LLMs
4251 | </Card>
4252 | </CardGroup>
4253 |
4254 |
4255 | # For Server Developers
4256 | Source: https://modelcontextprotocol.io/quickstart/server
4257 |
4258 | Get started building your own server to use in Claude for Desktop and other clients.
4259 |
4260 | In this tutorial, we'll build a simple MCP weather server and connect it to a host, Claude for Desktop. We'll start with a basic setup, and then progress to more complex use cases.
4261 |
4262 | ### What we'll be building
4263 |
4264 | Many LLMs (including Claude) do not currently have the ability to fetch the forecast and severe weather alerts. Let's use MCP to solve that!
4265 |
4266 | We'll build a server that exposes two tools: `get-alerts` and `get-forecast`. Then we'll connect the server to an MCP host (in this case, Claude for Desktop):
4267 |
4268 | <Frame>
4269 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/weather-alerts.png" />
4270 | </Frame>
4271 |
4272 | <Frame>
4273 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/current-weather.png" />
4274 | </Frame>
4275 |
4276 | <Note>
4277 | Servers can connect to any client. We've chosen Claude for Desktop here for simplicity, but we also have guides on [building your own client](/quickstart/client) as well as a [list of other clients here](/clients).
4278 | </Note>
4279 |
4280 | <Accordion title="Why Claude for Desktop and not Claude.ai?">
4281 | Because servers are locally run, MCP currently only supports desktop hosts. Remote hosts are in active development.
4282 | </Accordion>
4283 |
4284 | ### Core MCP Concepts
4285 |
4286 | MCP servers can provide three main types of capabilities:
4287 |
4288 | 1. **Resources**: File-like data that can be read by clients (like API responses or file contents)
4289 | 2. **Tools**: Functions that can be called by the LLM (with user approval)
4290 | 3. **Prompts**: Pre-written templates that help users accomplish specific tasks
4291 |
4292 | This tutorial will primarily focus on tools.
4293 |
4294 | <Tabs>
4295 | <Tab title="Python">
4296 | Let's get started with building our weather server! [You can find the complete code for what we'll be building here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-python)
4297 |
4298 | ### Prerequisite knowledge
4299 |
4300 | This quickstart assumes you have familiarity with:
4301 |
4302 | * Python
4303 | * LLMs like Claude
4304 |
4305 | ### System requirements
4306 |
4307 | * Python 3.10 or higher installed.
4308 | * You must use the Python MCP SDK 1.2.0 or higher.
4309 |
4310 | ### Set up your environment
4311 |
4312 | First, let's install `uv` and set up our Python project and environment:
4313 |
4314 | <CodeGroup>
4315 | ```bash MacOS/Linux
4316 | curl -LsSf https://astral.sh/uv/install.sh | sh
4317 | ```
4318 |
4319 | ```powershell Windows
4320 | powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
4321 | ```
4322 | </CodeGroup>
4323 |
4324 | Make sure to restart your terminal afterwards to ensure that the `uv` command gets picked up.
4325 |
4326 | Now, let's create and set up our project:
4327 |
4328 | <CodeGroup>
4329 | ```bash MacOS/Linux
4330 | # Create a new directory for our project
4331 | uv init weather
4332 | cd weather
4333 |
4334 | # Create virtual environment and activate it
4335 | uv venv
4336 | source .venv/bin/activate
4337 |
4338 | # Install dependencies
4339 | uv add "mcp[cli]" httpx
4340 |
4341 | # Create our server file
4342 | touch weather.py
4343 | ```
4344 |
4345 | ```powershell Windows
4346 | # Create a new directory for our project
4347 | uv init weather
4348 | cd weather
4349 |
4350 | # Create virtual environment and activate it
4351 | uv venv
4352 | .venv\Scripts\activate
4353 |
4354 | # Install dependencies
4355 | uv add mcp[cli] httpx
4356 |
4357 | # Create our server file
4358 | new-item weather.py
4359 | ```
4360 | </CodeGroup>
4361 |
4362 | Now let's dive into building your server.
4363 |
4364 | ## Building your server
4365 |
4366 | ### Importing packages and setting up the instance
4367 |
4368 | Add these to the top of your `weather.py`:
4369 |
4370 | ```python
4371 | from typing import Any
4372 | import httpx
4373 | from mcp.server.fastmcp import FastMCP
4374 |
4375 | # Initialize FastMCP server
4376 | mcp = FastMCP("weather")
4377 |
4378 | # Constants
4379 | NWS_API_BASE = "https://api.weather.gov"
4380 | USER_AGENT = "weather-app/1.0"
4381 | ```
4382 |
4383 | The FastMCP class uses Python type hints and docstrings to automatically generate tool definitions, making it easy to create and maintain MCP tools.
4384 |
4385 | ### Helper functions
4386 |
4387 | Next, let's add our helper functions for querying and formatting the data from the National Weather Service API:
4388 |
4389 | ```python
4390 | async def make_nws_request(url: str) -> dict[str, Any] | None:
4391 | """Make a request to the NWS API with proper error handling."""
4392 | headers = {
4393 | "User-Agent": USER_AGENT,
4394 | "Accept": "application/geo+json"
4395 | }
4396 | async with httpx.AsyncClient() as client:
4397 | try:
4398 | response = await client.get(url, headers=headers, timeout=30.0)
4399 | response.raise_for_status()
4400 | return response.json()
4401 | except Exception:
4402 | return None
4403 |
4404 | def format_alert(feature: dict) -> str:
4405 | """Format an alert feature into a readable string."""
4406 | props = feature["properties"]
4407 | return f"""
4408 | Event: {props.get('event', 'Unknown')}
4409 | Area: {props.get('areaDesc', 'Unknown')}
4410 | Severity: {props.get('severity', 'Unknown')}
4411 | Description: {props.get('description', 'No description available')}
4412 | Instructions: {props.get('instruction', 'No specific instructions provided')}
4413 | """
4414 | ```
4415 |
4416 | ### Implementing tool execution
4417 |
4418 | The tool execution handler is responsible for actually executing the logic of each tool. Let's add it:
4419 |
4420 | ```python
4421 | @mcp.tool()
4422 | async def get_alerts(state: str) -> str:
4423 | """Get weather alerts for a US state.
4424 |
4425 | Args:
4426 | state: Two-letter US state code (e.g. CA, NY)
4427 | """
4428 | url = f"{NWS_API_BASE}/alerts/active/area/{state}"
4429 | data = await make_nws_request(url)
4430 |
4431 | if not data or "features" not in data:
4432 | return "Unable to fetch alerts or no alerts found."
4433 |
4434 | if not data["features"]:
4435 | return "No active alerts for this state."
4436 |
4437 | alerts = [format_alert(feature) for feature in data["features"]]
4438 | return "\n---\n".join(alerts)
4439 |
4440 | @mcp.tool()
4441 | async def get_forecast(latitude: float, longitude: float) -> str:
4442 | """Get weather forecast for a location.
4443 |
4444 | Args:
4445 | latitude: Latitude of the location
4446 | longitude: Longitude of the location
4447 | """
4448 | # First get the forecast grid endpoint
4449 | points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
4450 | points_data = await make_nws_request(points_url)
4451 |
4452 | if not points_data:
4453 | return "Unable to fetch forecast data for this location."
4454 |
4455 | # Get the forecast URL from the points response
4456 | forecast_url = points_data["properties"]["forecast"]
4457 | forecast_data = await make_nws_request(forecast_url)
4458 |
4459 | if not forecast_data:
4460 | return "Unable to fetch detailed forecast."
4461 |
4462 | # Format the periods into a readable forecast
4463 | periods = forecast_data["properties"]["periods"]
4464 | forecasts = []
4465 | for period in periods[:5]: # Only show next 5 periods
4466 | forecast = f"""
4467 | {period['name']}:
4468 | Temperature: {period['temperature']}°{period['temperatureUnit']}
4469 | Wind: {period['windSpeed']} {period['windDirection']}
4470 | Forecast: {period['detailedForecast']}
4471 | """
4472 | forecasts.append(forecast)
4473 |
4474 | return "\n---\n".join(forecasts)
4475 | ```
4476 |
4477 | ### Running the server
4478 |
4479 | Finally, let's initialize and run the server:
4480 |
4481 | ```python
4482 | if __name__ == "__main__":
4483 | # Initialize and run the server
4484 | mcp.run(transport='stdio')
4485 | ```
4486 |
4487 | Your server is complete! Run `uv run weather.py` to confirm that everything's working.
4488 |
4489 | Let's now test your server from an existing MCP host, Claude for Desktop.
4490 |
4491 | ## Testing your server with Claude for Desktop
4492 |
4493 | <Note>
4494 | Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/quickstart/client) tutorial to build an MCP client that connects to the server we just built.
4495 | </Note>
4496 |
4497 | First, make sure you have Claude for Desktop installed. [You can install the latest version
4498 | here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
4499 |
4500 | We'll need to configure Claude for Desktop for whichever MCP servers you want to use. To do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor. Make sure to create the file if it doesn't exist.
4501 |
4502 | For example, if you have [VS Code](https://code.visualstudio.com/) installed:
4503 |
4504 | <Tabs>
4505 | <Tab title="MacOS/Linux">
4506 | ```bash
4507 | code ~/Library/Application\ Support/Claude/claude_desktop_config.json
4508 | ```
4509 | </Tab>
4510 |
4511 | <Tab title="Windows">
4512 | ```powershell
4513 | code $env:AppData\Claude\claude_desktop_config.json
4514 | ```
4515 | </Tab>
4516 | </Tabs>
4517 |
4518 | You'll then add your servers in the `mcpServers` key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.
4519 |
4520 | In this case, we'll add our single weather server like so:
4521 |
4522 | <Tabs>
4523 | <Tab title="MacOS/Linux">
4524 | ```json Python
4525 | {
4526 | "mcpServers": {
4527 | "weather": {
4528 | "command": "uv",
4529 | "args": [
4530 | "--directory",
4531 | "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
4532 | "run",
4533 | "weather.py"
4534 | ]
4535 | }
4536 | }
4537 | }
4538 | ```
4539 | </Tab>
4540 |
4541 | <Tab title="Windows">
4542 | ```json Python
4543 | {
4544 | "mcpServers": {
4545 | "weather": {
4546 | "command": "uv",
4547 | "args": [
4548 | "--directory",
4549 | "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather",
4550 | "run",
4551 | "weather.py"
4552 | ]
4553 | }
4554 | }
4555 | }
4556 | ```
4557 | </Tab>
4558 | </Tabs>
4559 |
4560 | <Warning>
4561 | You may need to put the full path to the `uv` executable in the `command` field. You can get this by running `which uv` on MacOS/Linux or `where uv` on Windows.
4562 | </Warning>
4563 |
4564 | <Note>
4565 | Make sure you pass in the absolute path to your server.
4566 | </Note>
4567 |
4568 | This tells Claude for Desktop:
4569 |
4570 | 1. There's an MCP server named "weather"
4571 | 2. To launch it by running `uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather.py`
4572 |
4573 | Save the file, and restart **Claude for Desktop**.
4574 | </Tab>
4575 |
4576 | <Tab title="Node">
4577 | Let's get started with building our weather server! [You can find the complete code for what we'll be building here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-typescript)
4578 |
4579 | ### Prerequisite knowledge
4580 |
4581 | This quickstart assumes you have familiarity with:
4582 |
4583 | * TypeScript
4584 | * LLMs like Claude
4585 |
4586 | ### System requirements
4587 |
4588 | For TypeScript, make sure you have the latest version of Node installed.
4589 |
4590 | ### Set up your environment
4591 |
4592 | First, let's install Node.js and npm if you haven't already. You can download them from [nodejs.org](https://nodejs.org/).
4593 | Verify your Node.js installation:
4594 |
4595 | ```bash
4596 | node --version
4597 | npm --version
4598 | ```
4599 |
4600 | For this tutorial, you'll need Node.js version 16 or higher.
4601 |
4602 | Now, let's create and set up our project:
4603 |
4604 | <CodeGroup>
4605 | ```bash MacOS/Linux
4606 | # Create a new directory for our project
4607 | mkdir weather
4608 | cd weather
4609 |
4610 | # Initialize a new npm project
4611 | npm init -y
4612 |
4613 | # Install dependencies
4614 | npm install @modelcontextprotocol/sdk zod
4615 | npm install -D @types/node typescript
4616 |
4617 | # Create our files
4618 | mkdir src
4619 | touch src/index.ts
4620 | ```
4621 |
4622 | ```powershell Windows
4623 | # Create a new directory for our project
4624 | md weather
4625 | cd weather
4626 |
4627 | # Initialize a new npm project
4628 | npm init -y
4629 |
4630 | # Install dependencies
4631 | npm install @modelcontextprotocol/sdk zod
4632 | npm install -D @types/node typescript
4633 |
4634 | # Create our files
4635 | md src
4636 | new-item src\index.ts
4637 | ```
4638 | </CodeGroup>
4639 |
4640 | Update your package.json to add type: "module" and a build script:
4641 |
4642 | ```json package.json
4643 | {
4644 | "type": "module",
4645 | "bin": {
4646 | "weather": "./build/index.js"
4647 | },
4648 | "scripts": {
4649 | "build": "tsc && chmod 755 build/index.js"
4650 | },
4651 | "files": [
4652 | "build"
4653 | ],
4654 | }
4655 | ```
4656 |
4657 | Create a `tsconfig.json` in the root of your project:
4658 |
4659 | ```json tsconfig.json
4660 | {
4661 | "compilerOptions": {
4662 | "target": "ES2022",
4663 | "module": "Node16",
4664 | "moduleResolution": "Node16",
4665 | "outDir": "./build",
4666 | "rootDir": "./src",
4667 | "strict": true,
4668 | "esModuleInterop": true,
4669 | "skipLibCheck": true,
4670 | "forceConsistentCasingInFileNames": true
4671 | },
4672 | "include": ["src/**/*"],
4673 | "exclude": ["node_modules"]
4674 | }
4675 | ```
4676 |
4677 | Now let's dive into building your server.
4678 |
4679 | ## Building your server
4680 |
4681 | ### Importing packages and setting up the instance
4682 |
4683 | Add these to the top of your `src/index.ts`:
4684 |
4685 | ```typescript
4686 | import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
4687 | import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
4688 | import { z } from "zod";
4689 |
4690 | const NWS_API_BASE = "https://api.weather.gov";
4691 | const USER_AGENT = "weather-app/1.0";
4692 |
4693 | // Create server instance
4694 | const server = new McpServer({
4695 | name: "weather",
4696 | version: "1.0.0",
4697 | });
4698 | ```
4699 |
4700 | ### Helper functions
4701 |
4702 | Next, let's add our helper functions for querying and formatting the data from the National Weather Service API:
4703 |
4704 | ```typescript
4705 | // Helper function for making NWS API requests
4706 | async function makeNWSRequest<T>(url: string): Promise<T | null> {
4707 | const headers = {
4708 | "User-Agent": USER_AGENT,
4709 | Accept: "application/geo+json",
4710 | };
4711 |
4712 | try {
4713 | const response = await fetch(url, { headers });
4714 | if (!response.ok) {
4715 | throw new Error(`HTTP error! status: ${response.status}`);
4716 | }
4717 | return (await response.json()) as T;
4718 | } catch (error) {
4719 | console.error("Error making NWS request:", error);
4720 | return null;
4721 | }
4722 | }
4723 |
4724 | interface AlertFeature {
4725 | properties: {
4726 | event?: string;
4727 | areaDesc?: string;
4728 | severity?: string;
4729 | status?: string;
4730 | headline?: string;
4731 | };
4732 | }
4733 |
4734 | // Format alert data
4735 | function formatAlert(feature: AlertFeature): string {
4736 | const props = feature.properties;
4737 | return [
4738 | `Event: ${props.event || "Unknown"}`,
4739 | `Area: ${props.areaDesc || "Unknown"}`,
4740 | `Severity: ${props.severity || "Unknown"}`,
4741 | `Status: ${props.status || "Unknown"}`,
4742 | `Headline: ${props.headline || "No headline"}`,
4743 | "---",
4744 | ].join("\n");
4745 | }
4746 |
4747 | interface ForecastPeriod {
4748 | name?: string;
4749 | temperature?: number;
4750 | temperatureUnit?: string;
4751 | windSpeed?: string;
4752 | windDirection?: string;
4753 | shortForecast?: string;
4754 | }
4755 |
4756 | interface AlertsResponse {
4757 | features: AlertFeature[];
4758 | }
4759 |
4760 | interface PointsResponse {
4761 | properties: {
4762 | forecast?: string;
4763 | };
4764 | }
4765 |
4766 | interface ForecastResponse {
4767 | properties: {
4768 | periods: ForecastPeriod[];
4769 | };
4770 | }
4771 | ```
4772 |
4773 | ### Implementing tool execution
4774 |
4775 | The tool execution handler is responsible for actually executing the logic of each tool. Let's add it:
4776 |
4777 | ```typescript
4778 | // Register weather tools
4779 | server.tool(
4780 | "get-alerts",
4781 | "Get weather alerts for a state",
4782 | {
4783 | state: z.string().length(2).describe("Two-letter state code (e.g. CA, NY)"),
4784 | },
4785 | async ({ state }) => {
4786 | const stateCode = state.toUpperCase();
4787 | const alertsUrl = `${NWS_API_BASE}/alerts?area=${stateCode}`;
4788 | const alertsData = await makeNWSRequest<AlertsResponse>(alertsUrl);
4789 |
4790 | if (!alertsData) {
4791 | return {
4792 | content: [
4793 | {
4794 | type: "text",
4795 | text: "Failed to retrieve alerts data",
4796 | },
4797 | ],
4798 | };
4799 | }
4800 |
4801 | const features = alertsData.features || [];
4802 | if (features.length === 0) {
4803 | return {
4804 | content: [
4805 | {
4806 | type: "text",
4807 | text: `No active alerts for ${stateCode}`,
4808 | },
4809 | ],
4810 | };
4811 | }
4812 |
4813 | const formattedAlerts = features.map(formatAlert);
4814 | const alertsText = `Active alerts for ${stateCode}:\n\n${formattedAlerts.join("\n")}`;
4815 |
4816 | return {
4817 | content: [
4818 | {
4819 | type: "text",
4820 | text: alertsText,
4821 | },
4822 | ],
4823 | };
4824 | },
4825 | );
4826 |
4827 | server.tool(
4828 | "get-forecast",
4829 | "Get weather forecast for a location",
4830 | {
4831 | latitude: z.number().min(-90).max(90).describe("Latitude of the location"),
4832 | longitude: z.number().min(-180).max(180).describe("Longitude of the location"),
4833 | },
4834 | async ({ latitude, longitude }) => {
4835 | // Get grid point data
4836 | const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`;
4837 | const pointsData = await makeNWSRequest<PointsResponse>(pointsUrl);
4838 |
4839 | if (!pointsData) {
4840 | return {
4841 | content: [
4842 | {
4843 | type: "text",
4844 | text: `Failed to retrieve grid point data for coordinates: ${latitude}, ${longitude}. This location may not be supported by the NWS API (only US locations are supported).`,
4845 | },
4846 | ],
4847 | };
4848 | }
4849 |
4850 | const forecastUrl = pointsData.properties?.forecast;
4851 | if (!forecastUrl) {
4852 | return {
4853 | content: [
4854 | {
4855 | type: "text",
4856 | text: "Failed to get forecast URL from grid point data",
4857 | },
4858 | ],
4859 | };
4860 | }
4861 |
4862 | // Get forecast data
4863 | const forecastData = await makeNWSRequest<ForecastResponse>(forecastUrl);
4864 | if (!forecastData) {
4865 | return {
4866 | content: [
4867 | {
4868 | type: "text",
4869 | text: "Failed to retrieve forecast data",
4870 | },
4871 | ],
4872 | };
4873 | }
4874 |
4875 | const periods = forecastData.properties?.periods || [];
4876 | if (periods.length === 0) {
4877 | return {
4878 | content: [
4879 | {
4880 | type: "text",
4881 | text: "No forecast periods available",
4882 | },
4883 | ],
4884 | };
4885 | }
4886 |
4887 | // Format forecast periods
4888 | const formattedForecast = periods.map((period: ForecastPeriod) =>
4889 | [
4890 | `${period.name || "Unknown"}:`,
4891 | `Temperature: ${period.temperature || "Unknown"}°${period.temperatureUnit || "F"}`,
4892 | `Wind: ${period.windSpeed || "Unknown"} ${period.windDirection || ""}`,
4893 | `${period.shortForecast || "No forecast available"}`,
4894 | "---",
4895 | ].join("\n"),
4896 | );
4897 |
4898 | const forecastText = `Forecast for ${latitude}, ${longitude}:\n\n${formattedForecast.join("\n")}`;
4899 |
4900 | return {
4901 | content: [
4902 | {
4903 | type: "text",
4904 | text: forecastText,
4905 | },
4906 | ],
4907 | };
4908 | },
4909 | );
4910 | ```
4911 |
4912 | ### Running the server
4913 |
4914 | Finally, implement the main function to run the server:
4915 |
4916 | ```typescript
4917 | async function main() {
4918 | const transport = new StdioServerTransport();
4919 | await server.connect(transport);
4920 | console.error("Weather MCP Server running on stdio");
4921 | }
4922 |
4923 | main().catch((error) => {
4924 | console.error("Fatal error in main():", error);
4925 | process.exit(1);
4926 | });
4927 | ```
4928 |
4929 | Make sure to run `npm run build` to build your server! This is a very important step in getting your server to connect.
4930 |
4931 | Let's now test your server from an existing MCP host, Claude for Desktop.
4932 |
4933 | ## Testing your server with Claude for Desktop
4934 |
4935 | <Note>
4936 | Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/quickstart/client) tutorial to build an MCP client that connects to the server we just built.
4937 | </Note>
4938 |
4939 | First, make sure you have Claude for Desktop installed. [You can install the latest version
4940 | here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
4941 |
4942 | We'll need to configure Claude for Desktop for whichever MCP servers you want to use. To do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor. Make sure to create the file if it doesn't exist.
4943 |
4944 | For example, if you have [VS Code](https://code.visualstudio.com/) installed:
4945 |
4946 | <Tabs>
4947 | <Tab title="MacOS/Linux">
4948 | ```bash
4949 | code ~/Library/Application\ Support/Claude/claude_desktop_config.json
4950 | ```
4951 | </Tab>
4952 |
4953 | <Tab title="Windows">
4954 | ```powershell
4955 | code $env:AppData\Claude\claude_desktop_config.json
4956 | ```
4957 | </Tab>
4958 | </Tabs>
4959 |
4960 | You'll then add your servers in the `mcpServers` key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.
4961 |
4962 | In this case, we'll add our single weather server like so:
4963 |
4964 | <Tabs>
4965 | <Tab title="MacOS/Linux">
4966 | <CodeGroup>
4967 | ```json Node
4968 | {
4969 | "mcpServers": {
4970 | "weather": {
4971 | "command": "node",
4972 | "args": [
4973 | "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js"
4974 | ]
4975 | }
4976 | }
4977 | }
4978 | ```
4979 | </CodeGroup>
4980 | </Tab>
4981 |
4982 | <Tab title="Windows">
4983 | <CodeGroup>
4984 | ```json Node
4985 | {
4986 | "mcpServers": {
4987 | "weather": {
4988 | "command": "node",
4989 | "args": [
4990 | "C:\\PATH\\TO\\PARENT\\FOLDER\\weather\\build\\index.js"
4991 | ]
4992 | }
4993 | }
4994 | }
4995 | ```
4996 | </CodeGroup>
4997 | </Tab>
4998 | </Tabs>
4999 |
5000 | This tells Claude for Desktop:
5001 |
5002 | 1. There's an MCP server named "weather"
5003 | 2. Launch it by running `node /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js`
5004 |
5005 | Save the file, and restart **Claude for Desktop**.
5006 | </Tab>
5007 |
5008 | <Tab title="Java">
5009 | <Note>
5010 | This is a quickstart demo based on Spring AI MCP auto-configuration and boot starters.
5011 | To learn how to create sync and async MCP Servers, manually, consult the [Java SDK Server](/sdk/java/mcp-server) documentation.
5012 | </Note>
5013 |
5014 | Let's get started with building our weather server!
5015 | [You can find the complete code for what we'll be building here.](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-stdio-server)
5016 |
5017 | For more information, see the [MCP Server Boot Starter](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html) reference documentation.
5018 | For manual MCP Server implementation, refer to the [MCP Server Java SDK documentation](/sdk/java/mcp-server).
5019 |
5020 | ### System requirements
5021 |
5022 | * Java 17 or higher installed.
5023 | * [Spring Boot 3.3.x](https://docs.spring.io/spring-boot/installing.html) or higher
5024 |
5025 | ### Set up your environment
5026 |
5027 | Use the [Spring Initizer](https://start.spring.io/) to bootstrat the project.
5028 |
5029 | You will need to add the following dependencies:
5030 |
5031 | <Tabs>
5032 | <Tab title="Maven">
5033 | ```xml
5034 | <dependencies>
5035 | <dependency>
5036 | <groupId>org.springframework.ai</groupId>
5037 | <artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
5038 | </dependency>
5039 |
5040 | <dependency>
5041 | <groupId>org.springframework</groupId>
5042 | <artifactId>spring-web</artifactId>
5043 | </dependency>
5044 | </dependencies>
5045 | ```
5046 | </Tab>
5047 |
5048 | <Tab title="Gradle">
5049 | ```groovy
5050 | dependencies {
5051 | implementation platform("org.springframework.ai:spring-ai-mcp-server-spring-boot-starter")
5052 | implementation platform("org.springframework:spring-web")
5053 | }
5054 | ```
5055 | </Tab>
5056 | </Tabs>
5057 |
5058 | Then configure your application by setting the applicaiton properties:
5059 |
5060 | <CodeGroup>
5061 | ```bash application.properties
5062 | spring.main.bannerMode=off
5063 | logging.pattern.console=
5064 | ```
5065 |
5066 | ```yaml application.yml
5067 | logging:
5068 | pattern:
5069 | console:
5070 | spring:
5071 | main:
5072 | banner-mode: off
5073 | ```
5074 | </CodeGroup>
5075 |
5076 | The [Server Configuration Properties](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html#_configuration_properties) documents all available properties.
5077 |
5078 | Now let's dive into building your server.
5079 |
5080 | ## Building your server
5081 |
5082 | ### Weather Service
5083 |
5084 | Let's implement a [WeatheService.java](https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter-stdio-server/src/main/java/org/springframework/ai/mcp/sample/server/WeatherService.java) that uses a REST client to query the data from the National Weather Service API:
5085 |
5086 | ```java
5087 | @Service
5088 | public class WeatherService {
5089 |
5090 | private final RestClient restClient;
5091 |
5092 | public WeatherService() {
5093 | this.restClient = RestClient.builder()
5094 | .baseUrl("https://api.weather.gov")
5095 | .defaultHeader("Accept", "application/geo+json")
5096 | .defaultHeader("User-Agent", "WeatherApiClient/1.0 ([email protected])")
5097 | .build();
5098 | }
5099 |
5100 | @Tool(description = "Get weather forecast for a specific latitude/longitude")
5101 | public String getWeatherForecastByLocation(
5102 | double latitude, // Latitude coordinate
5103 | double longitude // Longitude coordinate
5104 | ) {
5105 | // Returns detailed forecast including:
5106 | // - Temperature and unit
5107 | // - Wind speed and direction
5108 | // - Detailed forecast description
5109 | }
5110 |
5111 | @Tool(description = "Get weather alerts for a US state")
5112 | public String getAlerts(
5113 | @ToolParam(description = "Two-letter US state code (e.g. CA, NY") String state)
5114 | ) {
5115 | // Returns active alerts including:
5116 | // - Event type
5117 | // - Affected area
5118 | // - Severity
5119 | // - Description
5120 | // - Safety instructions
5121 | }
5122 |
5123 | // ......
5124 | }
5125 | ```
5126 |
5127 | The `@Service` annotation with auto-register the service in your applicaiton context.
5128 | The Spring AI `@Tool` annotation, making it easy to create and maintain MCP tools.
5129 |
5130 | The auto-configuration will automatically register these tools with the MCP server.
5131 |
5132 | ### Create your Boot Applicaiton
5133 |
5134 | ```java
5135 | @SpringBootApplication
5136 | public class McpServerApplication {
5137 |
5138 | public static void main(String[] args) {
5139 | SpringApplication.run(McpServerApplication.class, args);
5140 | }
5141 |
5142 | @Bean
5143 | public ToolCallbackProvider weatherTools(WeatherService weatherService) {
5144 | return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
5145 | }
5146 | }
5147 | ```
5148 |
5149 | Uses the the `MethodToolCallbackProvider` utils to convert the `@Tools` into actionalble callbackes used by the MCP server.
5150 |
5151 | ### Running the server
5152 |
5153 | Finally, let's build the server:
5154 |
5155 | ```bash
5156 | ./mvnw clean install
5157 | ```
5158 |
5159 | This will generate a `mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar` file within the `target` folder.
5160 |
5161 | Let's now test your server from an existing MCP host, Claude for Desktop.
5162 |
5163 | ## Testing your server with Claude for Desktop
5164 |
5165 | <Note>
5166 | Claude for Desktop is not yet available on Linux.
5167 | </Note>
5168 |
5169 | First, make sure you have Claude for Desktop installed.
5170 | [You can install the latest version here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
5171 |
5172 | We'll need to configure Claude for Desktop for whichever MCP servers you want to use.
5173 | To do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor.
5174 | Make sure to create the file if it doesn't exist.
5175 |
5176 | For example, if you have [VS Code](https://code.visualstudio.com/) installed:
5177 |
5178 | <Tabs>
5179 | <Tab title="MacOS/Linux">
5180 | ```bash
5181 | code ~/Library/Application\ Support/Claude/claude_desktop_config.json
5182 | ```
5183 | </Tab>
5184 |
5185 | <Tab title="Windows">
5186 | ```powershell
5187 | code $env:AppData\Claude\claude_desktop_config.json
5188 | ```
5189 | </Tab>
5190 | </Tabs>
5191 |
5192 | You'll then add your servers in the `mcpServers` key.
5193 | The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.
5194 |
5195 | In this case, we'll add our single weather server like so:
5196 |
5197 | <Tabs>
5198 | <Tab title="MacOS/Linux">
5199 | ```json java
5200 | {
5201 | "mcpServers": {
5202 | "spring-ai-mcp-weather": {
5203 | "command": "java",
5204 | "args": [
5205 | "-Dspring.ai.mcp.server.stdio=true",
5206 | "-jar",
5207 | "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
5208 | ]
5209 | }
5210 | }
5211 | }
5212 | ```
5213 | </Tab>
5214 |
5215 | <Tab title="Windows">
5216 | ```json java
5217 | {
5218 | "mcpServers": {
5219 | "spring-ai-mcp-weather": {
5220 | "command": "java",
5221 | "args": [
5222 | "-Dspring.ai.mcp.server.transport=STDIO",
5223 | "-jar",
5224 | "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather\\mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
5225 | ]
5226 | }
5227 | }
5228 | }
5229 | ```
5230 | </Tab>
5231 | </Tabs>
5232 |
5233 | <Note>
5234 | Make sure you pass in the absolute path to your server.
5235 | </Note>
5236 |
5237 | This tells Claude for Desktop:
5238 |
5239 | 1. There's an MCP server named "my-weather-server"
5240 | 2. To launch it by running `java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar`
5241 |
5242 | Save the file, and restart **Claude for Desktop**.
5243 |
5244 | ## Testing your server with Java client
5245 |
5246 | ### Create a MCP Client manually
5247 |
5248 | Use the `McpClient` to connect to the server:
5249 |
5250 | ```java
5251 | var stdioParams = ServerParameters.builder("java")
5252 | .args("-jar", "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar")
5253 | .build();
5254 |
5255 | var stdioTransport = new StdioClientTransport(stdioParams);
5256 |
5257 | var mcpClient = McpClient.sync(stdioTransport).build();
5258 |
5259 | mcpClient.initialize();
5260 |
5261 | ListToolsResult toolsList = mcpClient.listTools();
5262 |
5263 | CallToolResult weather = mcpClient.callTool(
5264 | new CallToolRequest("getWeatherForecastByLocation",
5265 | Map.of("latitude", "47.6062", "longitude", "-122.3321")));
5266 |
5267 | CallToolResult alert = mcpClient.callTool(
5268 | new CallToolRequest("getAlerts", Map.of("state", "NY")));
5269 |
5270 | mcpClient.closeGracefully();
5271 | ```
5272 |
5273 | ### Use MCP Client Boot Starter
5274 |
5275 | Create a new boot starter applicaiton using the `spring-ai-mcp-client-spring-boot-starter` dependency:
5276 |
5277 | ```xml
5278 | <dependency>
5279 | <groupId>org.springframework.ai</groupId>
5280 | <artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
5281 | </dependency>
5282 | ```
5283 |
5284 | and set the `spring.ai.mcp.client.stdio.servers-configuration` property to point to your `claude_desktop_config.json`.
5285 | You can re-use the existing Anthropic Destop configuration:
5286 |
5287 | ```properties
5288 | spring.ai.mcp.client.stdio.servers-configuration=file:PATH/TO/claude_desktop_config.json
5289 | ```
5290 |
5291 | When you stasrt your client applicaiton, the auto-configuration will create, automatically MCP clients from the claude\_desktop\_config.json.
5292 |
5293 | For more information, see the [MCP Client Boot Starters](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-client-docs.html) reference documentation.
5294 |
5295 | ## More Java MCP Server examples
5296 |
5297 | The [starter-webflux-server](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-webflux-server) demonstrates how to create a MCP server using SSE transport.
5298 | It showcases how to define and register MCP Tools, Resources, and Prompts, using the Spring Boot's auto-configuration capabilities.
5299 | </Tab>
5300 | </Tabs>
5301 |
5302 | ### Test with commands
5303 |
5304 | Let's make sure Claude for Desktop is picking up the two tools we've exposed in our `weather` server. You can do this by looking for the hammer <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon:
5305 |
5306 | <Frame>
5307 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/visual-indicator-mcp-tools.png" />
5308 | </Frame>
5309 |
5310 | After clicking on the hammer icon, you should see two tools listed:
5311 |
5312 | <Frame>
5313 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/available-mcp-tools.png" />
5314 | </Frame>
5315 |
5316 | If your server isn't being picked up by Claude for Desktop, proceed to the [Troubleshooting](#troubleshooting) section for debugging tips.
5317 |
5318 | If the hammer icon has shown up, you can now test your server by running the following commands in Claude for Desktop:
5319 |
5320 | * What's the weather in Sacramento?
5321 | * What are the active weather alerts in Texas?
5322 |
5323 | <Frame>
5324 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/current-weather.png" />
5325 | </Frame>
5326 |
5327 | <Frame>
5328 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/weather-alerts.png" />
5329 | </Frame>
5330 |
5331 | <Note>
5332 | Since this is the US National Weather service, the queries will only work for US locations.
5333 | </Note>
5334 |
5335 | ## What's happening under the hood
5336 |
5337 | When you ask a question:
5338 |
5339 | 1. The client sends your question to Claude
5340 | 2. Claude analyzes the available tools and decides which one(s) to use
5341 | 3. The client executes the chosen tool(s) through the MCP server
5342 | 4. The results are sent back to Claude
5343 | 5. Claude formulates a natural language response
5344 | 6. The response is displayed to you!
5345 |
5346 | ## Troubleshooting
5347 |
5348 | <AccordionGroup>
5349 | <Accordion title="Claude for Desktop Integration Issues">
5350 | **Getting logs from Claude for Desktop**
5351 |
5352 | Claude.app logging related to MCP is written to log files in `~/Library/Logs/Claude`:
5353 |
5354 | * `mcp.log` will contain general logging about MCP connections and connection failures.
5355 | * Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server.
5356 |
5357 | You can run the following command to list recent logs and follow along with any new ones:
5358 |
5359 | ```bash
5360 | # Check Claude's logs for errors
5361 | tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
5362 | ```
5363 |
5364 | **Server not showing up in Claude**
5365 |
5366 | 1. Check your `claude_desktop_config.json` file syntax
5367 | 2. Make sure the path to your project is absolute and not relative
5368 | 3. Restart Claude for Desktop completely
5369 |
5370 | **Tool calls failing silently**
5371 |
5372 | If Claude attempts to use the tools but they fail:
5373 |
5374 | 1. Check Claude's logs for errors
5375 | 2. Verify your server builds and runs without errors
5376 | 3. Try restarting Claude for Desktop
5377 |
5378 | **None of this is working. What do I do?**
5379 |
5380 | Please refer to our [debugging guide](/docs/tools/debugging) for better debugging tools and more detailed guidance.
5381 | </Accordion>
5382 |
5383 | <Accordion title="Weather API Issues">
5384 | **Error: Failed to retrieve grid point data**
5385 |
5386 | This usually means either:
5387 |
5388 | 1. The coordinates are outside the US
5389 | 2. The NWS API is having issues
5390 | 3. You're being rate limited
5391 |
5392 | Fix:
5393 |
5394 | * Verify you're using US coordinates
5395 | * Add a small delay between requests
5396 | * Check the NWS API status page
5397 |
5398 | **Error: No active alerts for \[STATE]**
5399 |
5400 | This isn't an error - it just means there are no current weather alerts for that state. Try a different state or check during severe weather.
5401 | </Accordion>
5402 | </AccordionGroup>
5403 |
5404 | <Note>
5405 | For more advanced troubleshooting, check out our guide on [Debugging MCP](/docs/tools/debugging)
5406 | </Note>
5407 |
5408 | ## Next steps
5409 |
5410 | <CardGroup cols={2}>
5411 | <Card title="Building a client" icon="outlet" href="/quickstart/client">
5412 | Learn how to build your own MCP client that can connect to your server
5413 | </Card>
5414 |
5415 | <Card title="Example servers" icon="grid" href="/examples">
5416 | Check out our gallery of official MCP servers and implementations
5417 | </Card>
5418 |
5419 | <Card title="Debugging Guide" icon="bug" href="/docs/tools/debugging">
5420 | Learn how to effectively debug MCP servers and integrations
5421 | </Card>
5422 |
5423 | <Card title="Building MCP with LLMs" icon="comments" href="/tutorials/building-mcp-with-llms">
5424 | Learn how to use LLMs like Claude to speed up your MCP development
5425 | </Card>
5426 | </CardGroup>
5427 |
5428 |
5429 | # For Claude Desktop Users
5430 | Source: https://modelcontextprotocol.io/quickstart/user
5431 |
5432 | Get started using pre-built servers in Claude for Desktop.
5433 |
5434 | In this tutorial, you will extend [Claude for Desktop](https://claude.ai/download) so that it can read from your computer's file system, write new files, move files, and even search files.
5435 |
5436 | <Frame>
5437 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-filesystem.png" />
5438 | </Frame>
5439 |
5440 | Don't worry — it will ask you for your permission before executing these actions!
5441 |
5442 | ## 1. Download Claude for Desktop
5443 |
5444 | Start by downloading [Claude for Desktop](https://claude.ai/download), choosing either macOS or Windows. (Linux is not yet supported for Claude for Desktop.)
5445 |
5446 | Follow the installation instructions.
5447 |
5448 | If you already have Claude for Desktop, make sure it's on the latest version by clicking on the Claude menu on your computer and selecting "Check for Updates..."
5449 |
5450 | <Accordion title="Why Claude for Desktop and not Claude.ai?">
5451 | Because servers are locally run, MCP currently only supports desktop hosts. Remote hosts are in active development.
5452 | </Accordion>
5453 |
5454 | ## 2. Add the Filesystem MCP Server
5455 |
5456 | To add this filesystem functionality, we will be installing a pre-built [Filesystem MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) to Claude for Desktop. This is one of dozens of [servers](https://github.com/modelcontextprotocol/servers/tree/main) created by Anthropic and the community.
5457 |
5458 | Get started by opening up the Claude menu on your computer and select "Settings..." Please note that these are not the Claude Account Settings found in the app window itself.
5459 |
5460 | This is what it should look like on a Mac:
5461 |
5462 | <Frame style={{ textAlign: 'center' }}>
5463 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-menu.png" width="400" />
5464 | </Frame>
5465 |
5466 | Click on "Developer" in the lefthand bar of the Settings pane, and then click on "Edit Config":
5467 |
5468 | <Frame>
5469 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-developer.png" />
5470 | </Frame>
5471 |
5472 | This will create a configuration file at:
5473 |
5474 | * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
5475 | * Windows: `%APPDATA%\Claude\claude_desktop_config.json`
5476 |
5477 | if you don't already have one, and will display the file in your file system.
5478 |
5479 | Open up the configuration file in any text editor. Replace the file contents with this:
5480 |
5481 | <Tabs>
5482 | <Tab title="MacOS/Linux">
5483 | ```json
5484 | {
5485 | "mcpServers": {
5486 | "filesystem": {
5487 | "command": "npx",
5488 | "args": [
5489 | "-y",
5490 | "@modelcontextprotocol/server-filesystem",
5491 | "/Users/username/Desktop",
5492 | "/Users/username/Downloads"
5493 | ]
5494 | }
5495 | }
5496 | }
5497 | ```
5498 | </Tab>
5499 |
5500 | <Tab title="Windows">
5501 | ```json
5502 | {
5503 | "mcpServers": {
5504 | "filesystem": {
5505 | "command": "npx",
5506 | "args": [
5507 | "-y",
5508 | "@modelcontextprotocol/server-filesystem",
5509 | "C:\\Users\\username\\Desktop",
5510 | "C:\\Users\\username\\Downloads"
5511 | ]
5512 | }
5513 | }
5514 | }
5515 | ```
5516 | </Tab>
5517 | </Tabs>
5518 |
5519 | Make sure to replace `username` with your computer's username. The paths should point to valid directories that you want Claude to be able to access and modify. It's set up to work for Desktop and Downloads, but you can add more paths as well.
5520 |
5521 | You will also need [Node.js](https://nodejs.org) on your computer for this to run properly. To verify you have Node installed, open the command line on your computer.
5522 |
5523 | * On macOS, open the Terminal from your Applications folder
5524 | * On Windows, press Windows + R, type "cmd", and press Enter
5525 |
5526 | Once in the command line, verify you have Node installed by entering in the following command:
5527 |
5528 | ```bash
5529 | node --version
5530 | ```
5531 |
5532 | If you get an error saying "command not found" or "node is not recognized", download Node from [nodejs.org](https://nodejs.org/).
5533 |
5534 | <Tip>
5535 | **How does the configuration file work?**
5536 |
5537 | This configuration file tells Claude for Desktop which MCP servers to start up every time you start the application. In this case, we have added one server called "filesystem" that will use the Node `npx` command to install and run `@modelcontextprotocol/server-filesystem`. This server, described [here](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem), will let you access your file system in Claude for Desktop.
5538 | </Tip>
5539 |
5540 | <Warning>
5541 | **Command Privileges**
5542 |
5543 | Claude for Desktop will run the commands in the configuration file with the permissions of your user account, and access to your local files. Only add commands if you understand and trust the source.
5544 | </Warning>
5545 |
5546 | ## 3. Restart Claude
5547 |
5548 | After updating your configuration file, you need to restart Claude for Desktop.
5549 |
5550 | Upon restarting, you should see a hammer <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon in the bottom right corner of the input box:
5551 |
5552 | <Frame>
5553 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-hammer.png" />
5554 | </Frame>
5555 |
5556 | After clicking on the hammer icon, you should see the tools that come with the Filesystem MCP Server:
5557 |
5558 | <Frame style={{ textAlign: 'center' }}>
5559 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-tools.png" width="400" />
5560 | </Frame>
5561 |
5562 | If your server isn't being picked up by Claude for Desktop, proceed to the [Troubleshooting](#troubleshooting) section for debugging tips.
5563 |
5564 | ## 4. Try it out!
5565 |
5566 | You can now talk to Claude and ask it about your filesystem. It should know when to call the relevant tools.
5567 |
5568 | Things you might try asking Claude:
5569 |
5570 | * Can you write a poem and save it to my desktop?
5571 | * What are some work-related files in my downloads folder?
5572 | * Can you take all the images on my desktop and move them to a new folder called "Images"?
5573 |
5574 | As needed, Claude will call the relevant tools and seek your approval before taking an action:
5575 |
5576 | <Frame style={{ textAlign: 'center' }}>
5577 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-approve.png" width="500" />
5578 | </Frame>
5579 |
5580 | ## Troubleshooting
5581 |
5582 | <AccordionGroup>
5583 | <Accordion title="Server not showing up in Claude / hammer icon missing">
5584 | 1. Restart Claude for Desktop completely
5585 | 2. Check your `claude_desktop_config.json` file syntax
5586 | 3. Make sure the file paths included in `claude_desktop_config.json` are valid and that they are absolute and not relative
5587 | 4. Look at [logs](#getting-logs-from-claude-for-desktop) to see why the server is not connecting
5588 | 5. In your command line, try manually running the server (replacing `username` as you did in `claude_desktop_config.json`) to see if you get any errors:
5589 |
5590 | <Tabs>
5591 | <Tab title="MacOS/Linux">
5592 | ```bash
5593 | npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads
5594 | ```
5595 | </Tab>
5596 |
5597 | <Tab title="Windows">
5598 | ```bash
5599 | npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads
5600 | ```
5601 | </Tab>
5602 | </Tabs>
5603 | </Accordion>
5604 |
5605 | <Accordion title="Getting logs from Claude for Desktop">
5606 | Claude.app logging related to MCP is written to log files in:
5607 |
5608 | * macOS: `~/Library/Logs/Claude`
5609 |
5610 | * Windows: `%APPDATA%\Claude\logs`
5611 |
5612 | * `mcp.log` will contain general logging about MCP connections and connection failures.
5613 |
5614 | * Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server.
5615 |
5616 | You can run the following command to list recent logs and follow along with any new ones (on Windows, it will only show recent logs):
5617 |
5618 | <Tabs>
5619 | <Tab title="MacOS/Linux">
5620 | ```bash
5621 | # Check Claude's logs for errors
5622 | tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
5623 | ```
5624 | </Tab>
5625 |
5626 | <Tab title="Windows">
5627 | ```bash
5628 | type "%APPDATA%\Claude\logs\mcp*.log"
5629 | ```
5630 | </Tab>
5631 | </Tabs>
5632 | </Accordion>
5633 |
5634 | <Accordion title="Tool calls failing silently">
5635 | If Claude attempts to use the tools but they fail:
5636 |
5637 | 1. Check Claude's logs for errors
5638 | 2. Verify your server builds and runs without errors
5639 | 3. Try restarting Claude for Desktop
5640 | </Accordion>
5641 |
5642 | <Accordion title="None of this is working. What do I do?">
5643 | Please refer to our [debugging guide](/docs/tools/debugging) for better debugging tools and more detailed guidance.
5644 | </Accordion>
5645 |
5646 | <Accordion title="ENOENT error and `${APPDATA}` in paths on Windows">
5647 | If your configured server fails to load, and you see within its logs an error referring to `${APPDATA}` within a path, you may need to add the expanded value of `%APPDATA%` to your `env` key in `claude_desktop_config.json`:
5648 |
5649 | ```json
5650 | {
5651 | "brave-search": {
5652 | "command": "npx",
5653 | "args": ["-y", "@modelcontextprotocol/server-brave-search"],
5654 | "env": {
5655 | "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
5656 | "BRAVE_API_KEY": "..."
5657 | }
5658 | }
5659 | }
5660 | ```
5661 |
5662 | With this change in place, launch Claude Desktop once again.
5663 |
5664 | <Warning>
5665 | **NPM should be installed globally**
5666 |
5667 | The `npx` command may continue to fail if you have not installed NPM globally. If NPM is already installed globally, you will find `%APPDATA%\npm` exists on your system. If not, you can install NPM globally by running the following command:
5668 |
5669 | ```bash
5670 | npm install -g npm
5671 | ```
5672 | </Warning>
5673 | </Accordion>
5674 | </AccordionGroup>
5675 |
5676 | ## Next steps
5677 |
5678 | <CardGroup cols={2}>
5679 | <Card title="Explore other servers" icon="grid" href="/examples">
5680 | Check out our gallery of official MCP servers and implementations
5681 | </Card>
5682 |
5683 | <Card title="Build your own server" icon="code" href="/quickstart/server">
5684 | Now build your own custom server to use in Claude for Desktop and other clients
5685 | </Card>
5686 | </CardGroup>
5687 |
5688 |
5689 | # MCP Client
5690 | Source: https://modelcontextprotocol.io/sdk/java/mcp-client
5691 |
5692 | Learn how to use the Model Context Protocol (MCP) client to interact with MCP servers
5693 |
5694 | # Model Context Protocol Client
5695 |
5696 | The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers. It implements the client-side of the protocol, handling:
5697 |
5698 | * Protocol version negotiation to ensure compatibility with servers
5699 | * Capability negotiation to determine available features
5700 | * Message transport and JSON-RPC communication
5701 | * Tool discovery and execution
5702 | * Resource access and management
5703 | * Prompt system interactions
5704 | * Optional features like roots management and sampling support
5705 |
5706 | The client provides both synchronous and asynchronous APIs for flexibility in different application contexts.
5707 |
5708 | <Tabs>
5709 | <Tab title="Sync API">
5710 | ```java
5711 | // Create a sync client with custom configuration
5712 | McpSyncClient client = McpClient.sync(transport)
5713 | .requestTimeout(Duration.ofSeconds(10))
5714 | .capabilities(ClientCapabilities.builder()
5715 | .roots(true) // Enable roots capability
5716 | .sampling() // Enable sampling capability
5717 | .build())
5718 | .sampling(request -> new CreateMessageResult(response))
5719 | .build();
5720 |
5721 | // Initialize connection
5722 | client.initialize();
5723 |
5724 | // List available tools
5725 | ListToolsResult tools = client.listTools();
5726 |
5727 | // Call a tool
5728 | CallToolResult result = client.callTool(
5729 | new CallToolRequest("calculator",
5730 | Map.of("operation", "add", "a", 2, "b", 3))
5731 | );
5732 |
5733 | // List and read resources
5734 | ListResourcesResult resources = client.listResources();
5735 | ReadResourceResult resource = client.readResource(
5736 | new ReadResourceRequest("resource://uri")
5737 | );
5738 |
5739 | // List and use prompts
5740 | ListPromptsResult prompts = client.listPrompts();
5741 | GetPromptResult prompt = client.getPrompt(
5742 | new GetPromptRequest("greeting", Map.of("name", "Spring"))
5743 | );
5744 |
5745 | // Add/remove roots
5746 | client.addRoot(new Root("file:///path", "description"));
5747 | client.removeRoot("file:///path");
5748 |
5749 | // Close client
5750 | client.closeGracefully();
5751 | ```
5752 | </Tab>
5753 |
5754 | <Tab title="Async API">
5755 | ```java
5756 | // Create an async client with custom configuration
5757 | McpAsyncClient client = McpClient.async(transport)
5758 | .requestTimeout(Duration.ofSeconds(10))
5759 | .capabilities(ClientCapabilities.builder()
5760 | .roots(true) // Enable roots capability
5761 | .sampling() // Enable sampling capability
5762 | .build())
5763 | .sampling(request -> Mono.just(new CreateMessageResult(response)))
5764 | .toolsChangeConsumer(tools -> Mono.fromRunnable(() -> {
5765 | logger.info("Tools updated: {}", tools);
5766 | }))
5767 | .resourcesChangeConsumer(resources -> Mono.fromRunnable(() -> {
5768 | logger.info("Resources updated: {}", resources);
5769 | }))
5770 | .promptsChangeConsumer(prompts -> Mono.fromRunnable(() -> {
5771 | logger.info("Prompts updated: {}", prompts);
5772 | }))
5773 | .build();
5774 |
5775 | // Initialize connection and use features
5776 | client.initialize()
5777 | .flatMap(initResult -> client.listTools())
5778 | .flatMap(tools -> {
5779 | return client.callTool(new CallToolRequest(
5780 | "calculator",
5781 | Map.of("operation", "add", "a", 2, "b", 3)
5782 | ));
5783 | })
5784 | .flatMap(result -> {
5785 | return client.listResources()
5786 | .flatMap(resources ->
5787 | client.readResource(new ReadResourceRequest("resource://uri"))
5788 | );
5789 | })
5790 | .flatMap(resource -> {
5791 | return client.listPrompts()
5792 | .flatMap(prompts ->
5793 | client.getPrompt(new GetPromptRequest(
5794 | "greeting",
5795 | Map.of("name", "Spring")
5796 | ))
5797 | );
5798 | })
5799 | .flatMap(prompt -> {
5800 | return client.addRoot(new Root("file:///path", "description"))
5801 | .then(client.removeRoot("file:///path"));
5802 | })
5803 | .doFinally(signalType -> {
5804 | client.closeGracefully().subscribe();
5805 | })
5806 | .subscribe();
5807 | ```
5808 | </Tab>
5809 | </Tabs>
5810 |
5811 | ## Client Transport
5812 |
5813 | The transport layer handles the communication between MCP clients and servers, providing different implementations for various use cases. The client transport manages message serialization, connection establishment, and protocol-specific communication patterns.
5814 |
5815 | <Tabs>
5816 | <Tab title="STDIO">
5817 | Creates transport for in-process based communication
5818 |
5819 | ```java
5820 | ServerParameters params = ServerParameters.builder("npx")
5821 | .args("-y", "@modelcontextprotocol/server-everything", "dir")
5822 | .build();
5823 | McpTransport transport = new StdioClientTransport(params);
5824 | ```
5825 | </Tab>
5826 |
5827 | <Tab title="SSE (HttpClient)">
5828 | Creates a framework agnostic (pure Java API) SSE client transport. Included in the core mcp module.
5829 |
5830 | ```java
5831 | McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
5832 | ```
5833 | </Tab>
5834 |
5835 | <Tab title="SSE (WebFlux)">
5836 | Creates WebFlux-based SSE client transport. Requires the mcp-webflux-sse-transport dependency.
5837 |
5838 | ```java
5839 | WebClient.Builder webClientBuilder = WebClient.builder()
5840 | .baseUrl("http://your-mcp-server");
5841 | McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);
5842 | ```
5843 | </Tab>
5844 | </Tabs>
5845 |
5846 | ## Client Capabilities
5847 |
5848 | The client can be configured with various capabilities:
5849 |
5850 | ```java
5851 | var capabilities = ClientCapabilities.builder()
5852 | .roots(true) // Enable filesystem roots support with list changes notifications
5853 | .sampling() // Enable LLM sampling support
5854 | .build();
5855 | ```
5856 |
5857 | ### Roots Support
5858 |
5859 | Roots define the boundaries of where servers can operate within the filesystem:
5860 |
5861 | ```java
5862 | // Add a root dynamically
5863 | client.addRoot(new Root("file:///path", "description"));
5864 |
5865 | // Remove a root
5866 | client.removeRoot("file:///path");
5867 |
5868 | // Notify server of roots changes
5869 | client.rootsListChangedNotification();
5870 | ```
5871 |
5872 | The roots capability allows servers to:
5873 |
5874 | * Request the list of accessible filesystem roots
5875 | * Receive notifications when the roots list changes
5876 | * Understand which directories and files they have access to
5877 |
5878 | ### Sampling Support
5879 |
5880 | Sampling enables servers to request LLM interactions ("completions" or "generations") through the client:
5881 |
5882 | ```java
5883 | // Configure sampling handler
5884 | Function<CreateMessageRequest, CreateMessageResult> samplingHandler = request -> {
5885 | // Sampling implementation that interfaces with LLM
5886 | return new CreateMessageResult(response);
5887 | };
5888 |
5889 | // Create client with sampling support
5890 | var client = McpClient.sync(transport)
5891 | .capabilities(ClientCapabilities.builder()
5892 | .sampling()
5893 | .build())
5894 | .sampling(samplingHandler)
5895 | .build();
5896 | ```
5897 |
5898 | This capability allows:
5899 |
5900 | * Servers to leverage AI capabilities without requiring API keys
5901 | * Clients to maintain control over model access and permissions
5902 | * Support for both text and image-based interactions
5903 | * Optional inclusion of MCP server context in prompts
5904 |
5905 | ## Using MCP Clients
5906 |
5907 | ### Tool Execution
5908 |
5909 | Tools are server-side functions that clients can discover and execute. The MCP client provides methods to list available tools and execute them with specific parameters. Each tool has a unique name and accepts a map of parameters.
5910 |
5911 | <Tabs>
5912 | <Tab title="Sync API">
5913 | ```java
5914 | // List available tools and their names
5915 | var tools = client.listTools();
5916 | tools.forEach(tool -> System.out.println(tool.getName()));
5917 |
5918 | // Execute a tool with parameters
5919 | var result = client.callTool("calculator", Map.of(
5920 | "operation", "add",
5921 | "a", 1,
5922 | "b", 2
5923 | ));
5924 | ```
5925 | </Tab>
5926 |
5927 | <Tab title="Async API">
5928 | ```java
5929 | // List available tools asynchronously
5930 | client.listTools()
5931 | .doOnNext(tools -> tools.forEach(tool ->
5932 | System.out.println(tool.getName())))
5933 | .subscribe();
5934 |
5935 | // Execute a tool asynchronously
5936 | client.callTool("calculator", Map.of(
5937 | "operation", "add",
5938 | "a", 1,
5939 | "b", 2
5940 | ))
5941 | .subscribe();
5942 | ```
5943 | </Tab>
5944 | </Tabs>
5945 |
5946 | ### Resource Access
5947 |
5948 | Resources represent server-side data sources that clients can access using URI templates. The MCP client provides methods to discover available resources and retrieve their contents through a standardized interface.
5949 |
5950 | <Tabs>
5951 | <Tab title="Sync API">
5952 | ```java
5953 | // List available resources and their names
5954 | var resources = client.listResources();
5955 | resources.forEach(resource -> System.out.println(resource.getName()));
5956 |
5957 | // Retrieve resource content using a URI template
5958 | var content = client.getResource("file", Map.of(
5959 | "path", "/path/to/file.txt"
5960 | ));
5961 | ```
5962 | </Tab>
5963 |
5964 | <Tab title="Async API">
5965 | ```java
5966 | // List available resources asynchronously
5967 | client.listResources()
5968 | .doOnNext(resources -> resources.forEach(resource ->
5969 | System.out.println(resource.getName())))
5970 | .subscribe();
5971 |
5972 | // Retrieve resource content asynchronously
5973 | client.getResource("file", Map.of(
5974 | "path", "/path/to/file.txt"
5975 | ))
5976 | .subscribe();
5977 | ```
5978 | </Tab>
5979 | </Tabs>
5980 |
5981 | ### Prompt System
5982 |
5983 | The prompt system enables interaction with server-side prompt templates. These templates can be discovered and executed with custom parameters, allowing for dynamic text generation based on predefined patterns.
5984 |
5985 | <Tabs>
5986 | <Tab title="Sync API">
5987 | ```java
5988 | // List available prompt templates
5989 | var prompts = client.listPrompts();
5990 | prompts.forEach(prompt -> System.out.println(prompt.getName()));
5991 |
5992 | // Execute a prompt template with parameters
5993 | var response = client.executePrompt("echo", Map.of(
5994 | "text", "Hello, World!"
5995 | ));
5996 | ```
5997 | </Tab>
5998 |
5999 | <Tab title="Async API">
6000 | ```java
6001 | // List available prompt templates asynchronously
6002 | client.listPrompts()
6003 | .doOnNext(prompts -> prompts.forEach(prompt ->
6004 | System.out.println(prompt.getName())))
6005 | .subscribe();
6006 |
6007 | // Execute a prompt template asynchronously
6008 | client.executePrompt("echo", Map.of(
6009 | "text", "Hello, World!"
6010 | ))
6011 | .subscribe();
6012 | ```
6013 | </Tab>
6014 | </Tabs>
6015 |
6016 |
6017 | # Overview
6018 | Source: https://modelcontextprotocol.io/sdk/java/mcp-overview
6019 |
6020 | Introduction to the Model Context Protocol (MCP) Java SDK
6021 |
6022 | Java SDK for the [Model Context Protocol](https://modelcontextprotocol.org/docs/concepts/architecture)
6023 | enables standardized integration between AI models and tools.
6024 |
6025 | ## Features
6026 |
6027 | * MCP Client and MCP Server implementations supporting:
6028 | * Protocol [version compatibility negotiation](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle/#initialization)
6029 | * [Tool](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/) discovery, execution, list change notifications
6030 | * [Resource](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/) management with URI templates
6031 | * [Roots](https://spec.modelcontextprotocol.io/specification/2024-11-05/client/roots/) list management and notifications
6032 | * [Prompt](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/) handling and management
6033 | * [Sampling](https://spec.modelcontextprotocol.io/specification/2024-11-05/client/sampling/) support for AI model interactions
6034 | * Multiple transport implementations:
6035 | * Default transports:
6036 | * Stdio-based transport for process-based communication
6037 | * Java HttpClient-based SSE client transport for HTTP SSE Client-side streaming
6038 | * Servlet-based SSE server transport for HTTP SSE Server streaming
6039 | * Spring-based transports:
6040 | * WebFlux SSE client and server transports for reactive HTTP streaming
6041 | * WebMVC SSE transport for servlet-based HTTP streaming
6042 | * Supports Synchronous and Asynchronous programming paradigms
6043 |
6044 | ## Architecture
6045 |
6046 | The SDK follows a layered architecture with clear separation of concerns:
6047 |
6048 | 
6049 |
6050 | * **Client/Server Layer (McpClient/McpServer)**: Both use McpSession for sync/async operations,
6051 | with McpClient handling client-side protocol operations and McpServer managing server-side protocol operations.
6052 | * **Session Layer (McpSession)**: Manages communication patterns and state using DefaultMcpSession implementation.
6053 | * **Transport Layer (McpTransport)**: Handles JSON-RPC message serialization/deserialization via:
6054 | * StdioTransport (stdin/stdout) in the core module
6055 | * HTTP SSE transports in dedicated transport modules (Java HttpClient, Spring WebFlux, Spring WebMVC)
6056 |
6057 | The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers.
6058 | It implements the client-side of the protocol.
6059 |
6060 | 
6061 |
6062 | The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients.
6063 | It implements the server-side of the protocol.
6064 |
6065 | 
6066 |
6067 | Key Interactions:
6068 |
6069 | * **Client/Server Initialization**: Transport setup, protocol compatibility check, capability negotiation, and implementation details exchange.
6070 | * **Message Flow**: JSON-RPC message handling with validation, type-safe response processing, and error handling.
6071 | * **Resource Management**: Resource discovery, URI template-based access, subscription system, and content retrieval.
6072 |
6073 | ## Dependencies
6074 |
6075 | Add the following Maven dependency to your project:
6076 |
6077 | <Tabs>
6078 | <Tab title="Maven">
6079 | The core MCP functionality:
6080 |
6081 | ```xml
6082 | <dependency>
6083 | <groupId>io.modelcontextprotocol.sdk</groupId>
6084 | <artifactId>mcp</artifactId>
6085 | </dependency>
6086 | ```
6087 |
6088 | For HTTP SSE transport implementations, add one of the following dependencies:
6089 |
6090 | ```xml
6091 | <!-- Spring WebFlux-based SSE client and server transport -->
6092 | <dependency>
6093 | <groupId>io.modelcontextprotocol.sdk</groupId>
6094 | <artifactId>mcp-spring-webflux</artifactId>
6095 | </dependency>
6096 |
6097 | <!-- Spring WebMVC-based SSE server transport -->
6098 | <dependency>
6099 | <groupId>io.modelcontextprotocol.sdk</groupId>
6100 | <artifactId>mcp-spring-webmvc</artifactId>
6101 | </dependency>
6102 | ```
6103 | </Tab>
6104 |
6105 | <Tab title="Gradle">
6106 | The core MCP functionality:
6107 |
6108 | ```groovy
6109 | dependencies {
6110 | implementation platform("io.modelcontextprotocol.sdk:mcp")
6111 | //...
6112 | }
6113 | ```
6114 |
6115 | For HTTP SSE transport implementations, add one of the following dependencies:
6116 |
6117 | ```groovy
6118 | // Spring WebFlux-based SSE client and server transport
6119 | dependencies {
6120 | implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webflux")
6121 | }
6122 |
6123 | // Spring WebMVC-based SSE server transport
6124 | dependencies {
6125 | implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webmvc")
6126 | }
6127 | ```
6128 | </Tab>
6129 | </Tabs>
6130 |
6131 | ### Bill of Materials (BOM)
6132 |
6133 | The Bill of Materials (BOM) declares the recommended versions of all the dependencies used by a given release.
6134 | Using the BOM from your application's build script avoids the need for you to specify and maintain the dependency versions yourself.
6135 | Instead, the version of the BOM you're using determines the utilized dependency versions.
6136 | It also ensures that you're using supported and tested versions of the dependencies by default, unless you choose to override them.
6137 |
6138 | Add the BOM to your project:
6139 |
6140 | <Tabs>
6141 | <Tab title="Maven">
6142 | ```xml
6143 | <dependencyManagement>
6144 | <dependencies>
6145 | <dependency>
6146 | <groupId>io.modelcontextprotocol.sdk</groupId>
6147 | <artifactId>mcp-bom</artifactId>
6148 | <version>0.7.0</version>
6149 | <type>pom</type>
6150 | <scope>import</scope>
6151 | </dependency>
6152 | </dependencies>
6153 | </dependencyManagement>
6154 | ```
6155 | </Tab>
6156 |
6157 | <Tab title="Gradle">
6158 | ```groovy
6159 | dependencies {
6160 | implementation platform("io.modelcontextprotocol.sdk:mcp-bom:0.7.0")
6161 | //...
6162 | }
6163 | ```
6164 |
6165 | Gradle users can also use the Spring AI MCP BOM by leveraging Gradle (5.0+) native support for declaring dependency constraints using a Maven BOM.
6166 | This is implemented by adding a 'platform' dependency handler method to the dependencies section of your Gradle build script.
6167 | As shown in the snippet above this can then be followed by version-less declarations of the Starter Dependencies for the one or more spring-ai modules you wish to use, e.g. spring-ai-openai.
6168 | </Tab>
6169 | </Tabs>
6170 |
6171 | Replace the version number with the version of the BOM you want to use.
6172 |
6173 | ### Available Dependencies
6174 |
6175 | The following dependencies are available and managed by the BOM:
6176 |
6177 | * Core Dependencies
6178 | * `io.modelcontextprotocol.sdk:mcp` - Core MCP library providing the base functionality and APIs for Model Context Protocol implementation.
6179 | * Transport Dependencies
6180 | * `io.modelcontextprotocol.sdk:mcp-spring-webflux` - WebFlux-based Server-Sent Events (SSE) transport implementation for reactive applications.
6181 | * `io.modelcontextprotocol.sdk:mcp-spring-webmvc` - WebMVC-based Server-Sent Events (SSE) transport implementation for servlet-based applications.
6182 | * Testing Dependencies
6183 | * `io.modelcontextprotocol.sdk:mcp-test` - Testing utilities and support for MCP-based applications.
6184 |
6185 |
6186 | # MCP Server
6187 | Source: https://modelcontextprotocol.io/sdk/java/mcp-server
6188 |
6189 | Learn how to implement and configure a Model Context Protocol (MCP) server
6190 |
6191 | ## Overview
6192 |
6193 | The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients. It implements the server-side of the protocol, responsible for:
6194 |
6195 | * Exposing tools that clients can discover and execute
6196 | * Managing resources with URI-based access patterns
6197 | * Providing prompt templates and handling prompt requests
6198 | * Supporting capability negotiation with clients
6199 | * Implementing server-side protocol operations
6200 | * Managing concurrent client connections
6201 | * Providing structured logging and notifications
6202 |
6203 | The server supports both synchronous and asynchronous APIs, allowing for flexible integration in different application contexts.
6204 |
6205 | <Tabs>
6206 | <Tab title="Sync API">
6207 | ```java
6208 | // Create a server with custom configuration
6209 | McpSyncServer syncServer = McpServer.sync(transport)
6210 | .serverInfo("my-server", "1.0.0")
6211 | .capabilities(ServerCapabilities.builder()
6212 | .resources(true) // Enable resource support
6213 | .tools(true) // Enable tool support
6214 | .prompts(true) // Enable prompt support
6215 | .logging() // Enable logging support
6216 | .build())
6217 | .build();
6218 |
6219 | // Register tools, resources, and prompts
6220 | syncServer.addTool(syncToolRegistration);
6221 | syncServer.addResource(syncResourceRegistration);
6222 | syncServer.addPrompt(syncPromptRegistration);
6223 |
6224 | // Send logging notifications
6225 | syncServer.loggingNotification(LoggingMessageNotification.builder()
6226 | .level(LoggingLevel.INFO)
6227 | .logger("custom-logger")
6228 | .data("Server initialized")
6229 | .build());
6230 |
6231 | // Close the server when done
6232 | syncServer.close();
6233 | ```
6234 | </Tab>
6235 |
6236 | <Tab title="Async API">
6237 | ```java
6238 | // Create an async server with custom configuration
6239 | McpAsyncServer asyncServer = McpServer.async(transport)
6240 | .serverInfo("my-server", "1.0.0")
6241 | .capabilities(ServerCapabilities.builder()
6242 | .resources(true) // Enable resource support
6243 | .tools(true) // Enable tool support
6244 | .prompts(true) // Enable prompt support
6245 | .logging() // Enable logging support
6246 | .build())
6247 | .build();
6248 |
6249 | // Register tools, resources, and prompts
6250 | asyncServer.addTool(asyncToolRegistration)
6251 | .doOnSuccess(v -> logger.info("Tool registered"))
6252 | .subscribe();
6253 |
6254 | asyncServer.addResource(asyncResourceRegistration)
6255 | .doOnSuccess(v -> logger.info("Resource registered"))
6256 | .subscribe();
6257 |
6258 | asyncServer.addPrompt(asyncPromptRegistration)
6259 | .doOnSuccess(v -> logger.info("Prompt registered"))
6260 | .subscribe();
6261 |
6262 | // Send logging notifications
6263 | asyncServer.loggingNotification(LoggingMessageNotification.builder()
6264 | .level(LoggingLevel.INFO)
6265 | .logger("custom-logger")
6266 | .data("Server initialized")
6267 | .build());
6268 |
6269 | // Close the server when done
6270 | asyncServer.close()
6271 | .doOnSuccess(v -> logger.info("Server closed"))
6272 | .subscribe();
6273 | ```
6274 | </Tab>
6275 | </Tabs>
6276 |
6277 | ## Server Transport
6278 |
6279 | The transport layer in the MCP SDK is responsible for handling the communication between clients and servers. It provides different implementations to support various communication protocols and patterns. The SDK includes several built-in transport implementations:
6280 |
6281 | <Tabs>
6282 | <Tab title="STDIO">
6283 | <>
6284 | Create in-process based transport:
6285 |
6286 | ```java
6287 | StdioServerTransport transport = new StdioServerTransport(new ObjectMapper());
6288 | ```
6289 |
6290 | Provides bidirectional JSON-RPC message handling over standard input/output streams with non-blocking message processing, serialization/deserialization, and graceful shutdown support.
6291 |
6292 | Key features:
6293 |
6294 | <ul>
6295 | <li>Bidirectional communication through stdin/stdout</li>
6296 | <li>Process-based integration support</li>
6297 | <li>Simple setup and configuration</li>
6298 | <li>Lightweight implementation</li>
6299 | </ul>
6300 | </>
6301 | </Tab>
6302 |
6303 | <Tab title="SSE (WebFlux)">
6304 | <>
6305 | <p>Creates WebFlux-based SSE server transport.<br />Requires the <code>mcp-spring-webflux</code> dependency.</p>
6306 |
6307 | ```java
6308 | @Configuration
6309 | class McpConfig {
6310 | @Bean
6311 | WebFluxSseServerTransport webFluxSseServerTransport(ObjectMapper mapper) {
6312 | return new WebFluxSseServerTransport(mapper, "/mcp/message");
6313 | }
6314 |
6315 | @Bean
6316 | RouterFunction<?> mcpRouterFunction(WebFluxSseServerTransport transport) {
6317 | return transport.getRouterFunction();
6318 | }
6319 | }
6320 | ```
6321 |
6322 | <p>Implements the MCP HTTP with SSE transport specification, providing:</p>
6323 |
6324 | <ul>
6325 | <li>Reactive HTTP streaming with WebFlux</li>
6326 | <li>Concurrent client connections through SSE endpoints</li>
6327 | <li>Message routing and session management</li>
6328 | <li>Graceful shutdown capabilities</li>
6329 | </ul>
6330 | </>
6331 | </Tab>
6332 |
6333 | <Tab title="SSE (WebMvc)">
6334 | <>
6335 | <p>Creates WebMvc-based SSE server transport.<br />Requires the <code>mcp-spring-webmvc</code> dependency.</p>
6336 |
6337 | ```java
6338 | @Configuration
6339 | @EnableWebMvc
6340 | class McpConfig {
6341 | @Bean
6342 | WebMvcSseServerTransport webMvcSseServerTransport(ObjectMapper mapper) {
6343 | return new WebMvcSseServerTransport(mapper, "/mcp/message");
6344 | }
6345 |
6346 | @Bean
6347 | RouterFunction<ServerResponse> mcpRouterFunction(WebMvcSseServerTransport transport) {
6348 | return transport.getRouterFunction();
6349 | }
6350 | }
6351 | ```
6352 |
6353 | <p>Implements the MCP HTTP with SSE transport specification, providing:</p>
6354 |
6355 | <ul>
6356 | <li>Server-side event streaming</li>
6357 | <li>Integration with Spring WebMVC</li>
6358 | <li>Support for traditional web applications</li>
6359 | <li>Synchronous operation handling</li>
6360 | </ul>
6361 | </>
6362 | </Tab>
6363 |
6364 | <Tab title="SSE (Servlet)">
6365 | <>
6366 | <p>
6367 | Creates a Servlet-based SSE server transport. It is included in the core <code>mcp</code> module.<br />
6368 | The <code>HttpServletSseServerTransport</code> can be used with any Servlet container.<br />
6369 | To use it with a Spring Web application, you can register it as a Servlet bean:
6370 | </p>
6371 |
6372 | ```java
6373 | @Configuration
6374 | @EnableWebMvc
6375 | public class McpServerConfig implements WebMvcConfigurer {
6376 |
6377 | @Bean
6378 | public HttpServletSseServerTransport servletSseServerTransport() {
6379 | return new HttpServletSseServerTransport(new ObjectMapper(), "/mcp/message");
6380 | }
6381 |
6382 | @Bean
6383 | public ServletRegistrationBean customServletBean(HttpServletSseServerTransport servlet) {
6384 | return new ServletRegistrationBean(servlet);
6385 | }
6386 | }
6387 | ```
6388 |
6389 | <p>
6390 | Implements the MCP HTTP with SSE transport specification using the traditional Servlet API, providing:
6391 | </p>
6392 |
6393 | <ul>
6394 | <li>Asynchronous message handling using Servlet 6.0 async support</li>
6395 | <li>Session management for multiple client connections</li>
6396 |
6397 | <li>
6398 | Two types of endpoints:
6399 |
6400 | <ul>
6401 | <li>SSE endpoint (<code>/sse</code>) for server-to-client events</li>
6402 | <li>Message endpoint (configurable) for client-to-server requests</li>
6403 | </ul>
6404 | </li>
6405 |
6406 | <li>Error handling and response formatting</li>
6407 | <li>Graceful shutdown support</li>
6408 | </ul>
6409 | </>
6410 | </Tab>
6411 | </Tabs>
6412 |
6413 | ## Server Capabilities
6414 |
6415 | The server can be configured with various capabilities:
6416 |
6417 | ```java
6418 | var capabilities = ServerCapabilities.builder()
6419 | .resources(false, true) // Resource support with list changes notifications
6420 | .tools(true) // Tool support with list changes notifications
6421 | .prompts(true) // Prompt support with list changes notifications
6422 | .logging() // Enable logging support (enabled by default with loging level INFO)
6423 | .build();
6424 | ```
6425 |
6426 | ### Logging Support
6427 |
6428 | The server provides structured logging capabilities that allow sending log messages to clients with different severity levels:
6429 |
6430 | ```java
6431 | // Send a log message to clients
6432 | server.loggingNotification(LoggingMessageNotification.builder()
6433 | .level(LoggingLevel.INFO)
6434 | .logger("custom-logger")
6435 | .data("Custom log message")
6436 | .build());
6437 | ```
6438 |
6439 | Clients can control the minimum logging level they receive through the `mcpClient.setLoggingLevel(level)` request. Messages below the set level will be filtered out.
6440 | Supported logging levels (in order of increasing severity): DEBUG (0), INFO (1), NOTICE (2), WARNING (3), ERROR (4), CRITICAL (5), ALERT (6), EMERGENCY (7)
6441 |
6442 | ### Tool Registration
6443 |
6444 | <Tabs>
6445 | <Tab title="Sync">
6446 | ```java
6447 | // Sync tool registration
6448 | var schema = """
6449 | {
6450 | "type" : "object",
6451 | "id" : "urn:jsonschema:Operation",
6452 | "properties" : {
6453 | "operation" : {
6454 | "type" : "string"
6455 | },
6456 | "a" : {
6457 | "type" : "number"
6458 | },
6459 | "b" : {
6460 | "type" : "number"
6461 | }
6462 | }
6463 | }
6464 | """;
6465 | var syncToolRegistration = new McpServerFeatures.SyncToolRegistration(
6466 | new Tool("calculator", "Basic calculator", schema),
6467 | arguments -> {
6468 | // Tool implementation
6469 | return new CallToolResult(result, false);
6470 | }
6471 | );
6472 | ```
6473 | </Tab>
6474 |
6475 | <Tab title="Async">
6476 | ```java
6477 | // Async tool registration
6478 | var schema = """
6479 | {
6480 | "type" : "object",
6481 | "id" : "urn:jsonschema:Operation",
6482 | "properties" : {
6483 | "operation" : {
6484 | "type" : "string"
6485 | },
6486 | "a" : {
6487 | "type" : "number"
6488 | },
6489 | "b" : {
6490 | "type" : "number"
6491 | }
6492 | }
6493 | }
6494 | """;
6495 | var asyncToolRegistration = new McpServerFeatures.AsyncToolRegistration(
6496 | new Tool("calculator", "Basic calculator", schema),
6497 | arguments -> {
6498 | // Tool implementation
6499 | return Mono.just(new CallToolResult(result, false));
6500 | }
6501 | );
6502 | ```
6503 | </Tab>
6504 | </Tabs>
6505 |
6506 | ### Resource Registration
6507 |
6508 | <Tabs>
6509 | <Tab title="Sync">
6510 | ```java
6511 | // Sync resource registration
6512 | var syncResourceRegistration = new McpServerFeatures.SyncResourceRegistration(
6513 | new Resource("custom://resource", "name", "description", "mime-type", null),
6514 | request -> {
6515 | // Resource read implementation
6516 | return new ReadResourceResult(contents);
6517 | }
6518 | );
6519 | ```
6520 | </Tab>
6521 |
6522 | <Tab title="Async">
6523 | ```java
6524 | // Async resource registration
6525 | var asyncResourceRegistration = new McpServerFeatures.AsyncResourceRegistration(
6526 | new Resource("custom://resource", "name", "description", "mime-type", null),
6527 | request -> {
6528 | // Resource read implementation
6529 | return Mono.just(new ReadResourceResult(contents));
6530 | }
6531 | );
6532 | ```
6533 | </Tab>
6534 | </Tabs>
6535 |
6536 | ### Prompt Registration
6537 |
6538 | <Tabs>
6539 | <Tab title="Sync">
6540 | ```java
6541 | // Sync prompt registration
6542 | var syncPromptRegistration = new McpServerFeatures.SyncPromptRegistration(
6543 | new Prompt("greeting", "description", List.of(
6544 | new PromptArgument("name", "description", true)
6545 | )),
6546 | request -> {
6547 | // Prompt implementation
6548 | return new GetPromptResult(description, messages);
6549 | }
6550 | );
6551 | ```
6552 | </Tab>
6553 |
6554 | <Tab title="Async">
6555 | ```java
6556 | // Async prompt registration
6557 | var asyncPromptRegistration = new McpServerFeatures.AsyncPromptRegistration(
6558 | new Prompt("greeting", "description", List.of(
6559 | new PromptArgument("name", "description", true)
6560 | )),
6561 | request -> {
6562 | // Prompt implementation
6563 | return Mono.just(new GetPromptResult(description, messages));
6564 | }
6565 | );
6566 | ```
6567 | </Tab>
6568 | </Tabs>
6569 |
6570 | ## Error Handling
6571 |
6572 | The SDK provides comprehensive error handling through the McpError class, covering protocol compatibility, transport communication, JSON-RPC messaging, tool execution, resource management, prompt handling, timeouts, and connection issues. This unified error handling approach ensures consistent and reliable error management across both synchronous and asynchronous operations.
6573 |
6574 |
6575 | # Building MCP with LLMs
6576 | Source: https://modelcontextprotocol.io/tutorials/building-mcp-with-llms
6577 |
6578 | Speed up your MCP development using LLMs such as Claude!
6579 |
6580 | This guide will help you use LLMs to help you build custom Model Context Protocol (MCP) servers and clients. We'll be focusing on Claude for this tutorial, but you can do this with any frontier LLM.
6581 |
6582 | ## Preparing the documentation
6583 |
6584 | Before starting, gather the necessary documentation to help Claude understand MCP:
6585 |
6586 | 1. Visit [https://modelcontextprotocol.io/llms-full.txt](https://modelcontextprotocol.io/llms-full.txt) and copy the full documentation text
6587 | 2. Navigate to either the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) or [Python SDK repository](https://github.com/modelcontextprotocol/python-sdk)
6588 | 3. Copy the README files and other relevant documentation
6589 | 4. Paste these documents into your conversation with Claude
6590 |
6591 | ## Describing your server
6592 |
6593 | Once you've provided the documentation, clearly describe to Claude what kind of server you want to build. Be specific about:
6594 |
6595 | * What resources your server will expose
6596 | * What tools it will provide
6597 | * Any prompts it should offer
6598 | * What external systems it needs to interact with
6599 |
6600 | For example:
6601 |
6602 | ```
6603 | Build an MCP server that:
6604 | - Connects to my company's PostgreSQL database
6605 | - Exposes table schemas as resources
6606 | - Provides tools for running read-only SQL queries
6607 | - Includes prompts for common data analysis tasks
6608 | ```
6609 |
6610 | ## Working with Claude
6611 |
6612 | When working with Claude on MCP servers:
6613 |
6614 | 1. Start with the core functionality first, then iterate to add more features
6615 | 2. Ask Claude to explain any parts of the code you don't understand
6616 | 3. Request modifications or improvements as needed
6617 | 4. Have Claude help you test the server and handle edge cases
6618 |
6619 | Claude can help implement all the key MCP features:
6620 |
6621 | * Resource management and exposure
6622 | * Tool definitions and implementations
6623 | * Prompt templates and handlers
6624 | * Error handling and logging
6625 | * Connection and transport setup
6626 |
6627 | ## Best practices
6628 |
6629 | When building MCP servers with Claude:
6630 |
6631 | * Break down complex servers into smaller pieces
6632 | * Test each component thoroughly before moving on
6633 | * Keep security in mind - validate inputs and limit access appropriately
6634 | * Document your code well for future maintenance
6635 | * Follow MCP protocol specifications carefully
6636 |
6637 | ## Next steps
6638 |
6639 | After Claude helps you build your server:
6640 |
6641 | 1. Review the generated code carefully
6642 | 2. Test the server with the MCP Inspector tool
6643 | 3. Connect it to Claude.app or other MCP clients
6644 | 4. Iterate based on real usage and feedback
6645 |
6646 | Remember that Claude can help you modify and improve your server as requirements change over time.
6647 |
6648 | Need more guidance? Just ask Claude specific questions about implementing MCP features or troubleshooting issues that arise.
6649 |
6650 |
```