# MCP & Connector Configuration: Step-by-Step Training Guide > Hands-on configuration guide for every major MCP integration. Each section tells you exactly what information you need, walks through setup step-by-step, shows the architecture, and gives you a verification checklist. --- ## Guide progress | Part | Topic | Sections | |:----:|-------|----------| | **1** | Integration models | Architecture comparison, decision tree | | **2** | Web connectors | Microsoft 365, Slack, Google Workspace, Jira, Confluence, Salesforce, GitHub | | **3** | MCP servers | Protocol, CLI setup, reference servers, remote servers, debugging | | **4** | Enterprise Search | Architecture, setup, permissions, Drive Cataloging | | **5** | Custom MCP development | Design, implement, harden, test, deploy, govern | --- ## How this guide is organized Each integration follows a consistent pattern: | Step | What you'll see | |------|----------------| | **Capabilities** | What the integration does and its access model | | **Prerequisites** | Exactly what information, credentials, and access you need before you start | | **Architecture** | How data flows between Claude and the external service | | **Configuration** | Numbered, sequential steps — every click and command | | **Verification** | Checklist to confirm everything works | | **Troubleshooting** | Common failure modes and how to fix them | --- # Part 1 — Integration Models `Part 1 of 5` | Next: [Part 2 — Web Connectors](#part-2--web-connector-configuration) > **Key principle:** Claude supports two integration architectures. Choosing the right one up front saves weeks of work. You don't pick the integration — the integration's nature picks the model. ### The two models at a glance | | Web Connectors (Remote MCP) | MCP Servers (Local or Remote) | |---|---|---| | **Built by** | Anthropic (pre-built) | Reference, community, or your team | | **Infrastructure** | Anthropic-managed | You host and maintain | | **Configured via** | Admin Console (UI) | CLI commands or config files | | **Auth model** | OAuth per user (automatic) | Tokens/keys you manage | | **Available on** | All Claude surfaces | Claude Code, Claude Desktop | | **Examples** | Microsoft 365, Slack, Google Workspace, Jira, Confluence, Salesforce, GitHub | Filesystem, Git, Fetch, Memory, custom internal APIs | | **Best for** | SaaS apps with pre-built support | Internal tools, dev workflows, custom integrations | ### Decision tree > **Ask these questions in order. Stop at the first "yes."** **Question 1:** Does a pre-built web connector exist for this service? > **YES** → Use the web connector. Fastest path — Anthropic manages the infrastructure. **Go to Part 2.** **Question 2:** Is there an official reference or community MCP server? > **YES, and it meets your security requirements** → Deploy the reference server. **Go to Part 3.** > > **YES, but it doesn't meet your security requirements** → Build a custom MCP server. **Go to Part 5.** **Question 3:** None of the above? > Build a custom MCP server. **Go to Part 5.** --- # Part 2 — Web Connector Configuration `Part 2 of 5` | Previous: [Part 1](#part-1--integration-models) | Next: [Part 3](#part-3--mcp-server-configuration) > **Key principle:** Every web connector follows the same four-step admin flow. Connector-specific prerequisites are layered on top. Learn the pattern once, deploy any connector. ### Universal setup flow All seven web connectors follow this sequence. Admin steps come first; user steps follow. > **Step 1 · ORG ENABLEMENT** — *Admin action* > > Admin Console → Connectors → Browse → **Add to your team** > > Enables the connector for the org. Does NOT auto-connect any user. > **Step 2 · ACTION RESTRICTIONS** — *Admin action* > > Customize → Connectors → Select connector > > For each action, choose: **Always allow** · **Needs approval** · **Blocked** > **Connector-specific prerequisites** — *Varies by service* > > Some connectors require extra admin work before users can connect: > - **Microsoft 365** → Entra Global Admin pre-consent > - **Slack** → Workspace admin app approval > - **Salesforce** → Connected App configuration > - **Google Workspace** → Admin Console trusted app setting > **Step 3 · USER CONNECTS** — *User action* > > Chat → **+** → Connectors → Manage → **+** → Connect → **OAuth sign-in** > > Each user authenticates individually. Claude inherits their source-system permissions. > **Step 4 · ACTIVATE PER CONVERSATION** — *User action* > > Chat → **+** → Connectors → Toggle services on/off > > Choose tool access mode: **Auto** (default — Claude decides when to use connectors) or **On Demand** (recommended when 10+ connectors are active) > **Tip:** Restrictions can only *narrow* access, never expand it. If a user doesn't have permission in the source system, no admin setting can grant it through the connector. --- ## 2.1 Microsoft 365 `Connector 1 of 7` · Read-only · OAuth 2.0 OBO+PKCE > **"The M365 connector is read-only by design. Claude inherits each user's existing Microsoft permissions — it can never see more than the user can."** **Capabilities:** Search/read Outlook emails, search/retrieve SharePoint documents, search/access OneDrive files, search/read Teams messages. ### Prerequisites | # | Requirement | Provider | Location | |:-:|-------------|----------|----------| | 1 | Claude org Owner or Primary Owner role | Claude admin | Admin Console → Members | | 2 | Microsoft Entra Global Administrator access | Microsoft admin | Entra admin center | | 3 | Test user with active M365 license | IT team | Microsoft 365 admin center | | 4 | List of M365 data sources to expose | Security/compliance | Data classification review | ### Architecture **Data flow:** User → *OAuth 2.0 PKCE* → Claude MCP Server → *OBO token exchange* → Microsoft Graph API → data back to user | Stage | What happens | Detail | |:-----:|-------------|--------| | **1** | User authenticates | OAuth 2.0 with PKCE — browser redirect to Microsoft sign-in | | **2** | Token exchange | Claude MCP server exchanges user token for an On-Behalf-Of (OBO) token | | **3** | API calls | OBO token calls Microsoft Graph API as the authenticated user | | **4** | Results returned | Data flows back through Claude MCP server to the user | **Token lifecycle:** | Token | Expiry | Notes | |-------|--------|-------| | Access token | 60–90 minutes | Short-lived, auto-refreshed | | Refresh token | 90 days of inactivity | User must reconnect if idle too long | | OBO token | Server-side only | Never exposed to end user or Claude | > **Security guarantees:** Delegated permissions only (user's own M365 access) · Multi-tenant cryptographic isolation · All Graph API calls logged in your M365 audit log · SOC 2 Type II · ISO 27001 · GDPR compliant ### Configuration > **Warning:** Step 1 must be completed before any user can connect. Without Entra pre-consent, all user connection attempts fail silently. **Step 1 of 5 — Entra Global Admin pre-consent** 1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as Global Administrator 2. Navigate to **Enterprise applications** 3. Find the Claude connector application 4. Select **Permissions** → **Grant admin consent for [your tenant]** 5. Review the requested delegated permissions (read-only Graph API scopes) 6. Click **Accept** 7. Verify consent status shows "Granted for [tenant name]" **Step 2 of 5 — Enable in Claude Admin Console** 1. Log in to Claude as an **Owner** or **Primary Owner** 2. Navigate to **Organization settings** → **Connectors** 3. Click **Browse connectors** → **Add to your team** 4. Find **Microsoft 365** → click **Enable** 5. The connector is now available — no user is connected yet **Step 3 of 5 — Configure action restrictions** 1. Navigate to **Customize** → **Connectors** → **Microsoft 365** 2. Review available actions (all read-only for M365): | Action | Recommended setting | Notes | |--------|-------------------|-------| | Search emails | Needs approval → Always allow after pilot | Low risk | | Read email content | Needs approval → Always allow after pilot | Low risk | | Search SharePoint docs | Needs approval | Medium — may contain sensitive docs | | Read OneDrive files | Needs approval | Medium — personal files | | Search Teams messages | Needs approval | Medium — may contain candid discussion | > **Tip:** Start with "Needs approval" for everything during pilot. After 2–4 weeks of clean operation, relax to "Always allow" for low-risk actions. **Step 4 of 5 — Test user connection** 1. As a test user, open any Claude conversation 2. Click **+** → hover over **Connectors** → **Manage connectors** 3. Click **+** → find **Microsoft 365** → click **Connect** 4. Browser redirects to Microsoft sign-in 5. Sign in with your M365 credentials and accept the permissions prompt 6. Browser redirects back to Claude — connection confirmed **Step 5 of 5 — Activate and verify** 1. In a chat, click **+** → hover over **Connectors** 2. Toggle **Microsoft 365** on 3. Test: *"Search my recent emails about quarterly planning"* 4. Verify Claude returns results matching your M365 access ### Verification - [ ] Entra admin consent granted — check Enterprise applications → Permissions - [ ] Connector enabled in Claude Admin Console - [ ] Action restrictions configured per security requirements - [ ] Test user successfully connected via OAuth - [ ] Test user can query emails, documents, and messages - [ ] M365 audit log shows Graph API calls from the connector - [ ] User without access to a specific document cannot retrieve it via Claude ### Troubleshooting | Symptom | Cause | Resolution | |---------|-------|------------| | "Connection failed" on user connect | Entra pre-consent not completed | Complete Step 1 with Global Admin | | No results returned | User doesn't have M365 license | Verify active M365 subscription | | Partial results | User permissions in M365 are limited | Check M365 sharing/access controls | | Token expired errors | Refresh token inactive >90 days | User must reconnect — repeat Step 4 | --- ## 2.2 Slack `Connector 2 of 7` · Bi-directional (read + write) · OAuth > **"Slack is the only default-write connector. Block write actions on day one. Enable them deliberately after validation."** **Capabilities:** Search/read messages, channels, threads, files. Optionally: send messages, create channels, upload files. ### Prerequisites | # | Requirement | Provider | Location | |:-:|-------------|----------|----------| | 1 | Claude org Owner role | Claude admin | Admin Console → Members | | 2 | Slack workspace admin access | Slack admin | Slack admin settings | | 3 | Decision: read-only or read+write | Security team | Policy review | | 4 | Test channels to validate | Team leads | Slack channel list | ### Architecture **Two directions of data flow:** | Direction | Flow | Trigger | |-----------|------|---------| | **Read** (Slack → Claude) | User → *OAuth* → Claude MCP Server → *Slack API* → messages/files back to user | Always available | | **Write** (Claude → Slack) | User approves → Claude MCP Server → *Slack API* → posts message → confirmation | Only if admin enables write actions | > **Access model:** Claude sees only channels the user is a member of. Private channels require membership. DMs are limited to the user's own. Write actions respect the user's Slack permissions — Claude cannot post where the user cannot post. ### Configuration **Step 1 of 5 — Enable in Claude Admin Console** 1. Navigate to **Organization settings** → **Connectors** 2. Click **Browse connectors** → **Add to your team** 3. Find **Slack** → click **Enable** **Step 2 of 5 — Configure action restrictions** > **Important:** Slack is bi-directional. Configure write actions before any user connects. | Action | Recommended setting | Risk | |--------|-------------------|------| | Search messages | Always allow | Low | | Read channel history | Always allow | Low | | List channels | Always allow | Low | | **Send messages** | **Blocked** | High — Claude posts as the user | | **Create channels** | **Blocked** | Medium — org clutter | | **Upload files** | **Blocked** | Medium — data exfiltration vector | > **Tip:** Start read-only. After 2–4 weeks, consider enabling "Send messages" with "Needs approval" if teams request it. Keep "Create channels" and "Upload files" blocked. **Step 3 of 5 — Slack workspace approval** 1. Your Slack workspace admin navigates to **Manage apps** 2. Finds the Claude connector app and approves it 3. Optionally restricts which channels the app can access **Step 4 of 5 — User connection** 1. User opens Claude → **+** → **Connectors** → **Manage** → **+** 2. Find **Slack** → click **Connect** 3. OAuth flow redirects to Slack sign-in → authorize → connection confirmed **Step 5 of 5 — Verify** 1. Toggle Slack on in a conversation 2. Test: *"Summarize the last week of discussion in #general"* 3. Verify Claude returns messages only from channels the user can access ### Verification - [ ] Connector enabled in Claude Admin Console - [ ] All write actions blocked or set to "Needs approval" - [ ] Slack workspace admin approved the Claude app - [ ] Test user connected and can search messages - [ ] User cannot see private channels they're not a member of - [ ] Write actions respect configured restrictions --- ## 2.3 Google Workspace `Connector 3 of 7` · Read-only · OAuth 2.0 > **"Gmail read but no send. Calendar view but no create. Drive search but text only. The Google connector is deliberately conservative."** **Capabilities:** Gmail (search/read), Google Calendar (view events), Google Drive (search/read, text-only extraction). ### Prerequisites | # | Requirement | Provider | Location | |:-:|-------------|----------|----------| | 1 | Claude org Owner role | Claude admin | Admin Console | | 2 | Google Workspace admin access | Google admin | Google Admin Console | | 3 | Decision on which services to enable | Security team | Policy review | ### Architecture **Data flow:** User → *OAuth 2.0* → Claude MCP Server → *Google APIs* → results back to user | Service | Can do | Cannot do | |---------|--------|-----------| | **Gmail** | Search emails, read content | Send, reply, draft, delete | | **Calendar** | View events, read details | Create, modify, delete events | | **Drive** | Search files, read content (text only) | Access images, charts, formatting | > **Warning:** Drive extraction is text-only. Spreadsheet formulas, chart images, and rich formatting are not available through the connector. ### Configuration **Step 1 of 4 — Google Workspace admin approval** 1. Sign in to the [Google Admin Console](https://admin.google.com) 2. Navigate to **Security** → **API controls** → **App access control** 3. Find the Claude connector application 4. Set access to **Trusted** (allows OAuth consent for org users) 5. Optionally restrict to specific organizational units (OUs) **Step 2 of 4 — Enable in Claude Admin Console** 1. Navigate to **Organization settings** → **Connectors** 2. Enable **Google Workspace** (covers Gmail, Calendar, Drive) **Step 3 of 4 — Configure action restrictions** 1. Navigate to **Customize** → **Connectors** → **Google Workspace** 2. All actions are read-only by default — review and confirm **Step 4 of 4 — User connection and verification** 1. User connects via OAuth → Google sign-in → authorize → confirmed 2. Test: *"Search my Drive for the Q3 planning document"* 3. Verify: Claude cannot send emails (attempt should be rejected) ### Verification - [ ] Google Workspace admin marked Claude app as Trusted - [ ] Connector enabled in Claude Admin Console - [ ] Test user connected via OAuth - [ ] Gmail search returns results matching user's inbox - [ ] Drive search returns only files user has access to - [ ] Calendar queries show user's events - [ ] Confirm: Claude cannot send emails --- ## 2.4 Jira `Connector 4 of 7` · Read + Write · OAuth 2.0 > **"Jira write access is powerful — creating and transitioning issues programmatically. Start read-only and expand deliberately."** **Capabilities:** Search issues (JQL), read issue details/comments, create/update issues, batch operations, project navigation. ### Prerequisites | # | Requirement | Provider | Location | |:-:|-------------|----------|----------| | 1 | Claude org Owner role | Claude admin | Admin Console | | 2 | Jira site admin access | Atlassian admin | Jira settings | | 3 | Decision: read-only or read+write | Security team | Policy review | ### Architecture **Data flow:** User → *OAuth 2.0* → Claude MCP Server → *Jira REST API* → issues back to user | Access type | Capabilities | |------------|-------------| | **Read** | Search with JQL · View issues · Read comments · List projects | | **Write** | Create issues · Update fields · Add comments · Transition status | > **Access model:** Respects Jira project permissions and issue security levels. Users can only see and modify issues they have access to in Jira. ### Configuration **Step 1 of 3 — Enable and restrict** 1. Navigate to **Organization settings** → **Connectors** → enable **Jira** 2. Navigate to **Customize** → **Connectors** → **Jira** | Action | Recommended setting | |--------|-------------------| | Search issues (JQL) | Always allow | | View issue details | Always allow | | Read comments | Always allow | | **Create issues** | **Needs approval** or Blocked | | **Update issues** | **Needs approval** or Blocked | | **Add comments** | **Needs approval** | | **Transition status** | **Blocked** (initially) | **Step 2 of 3 — User connection** 1. User connects via Claude → OAuth with Atlassian account 2. User selects which Jira site(s) to connect **Step 3 of 3 — Verify** Test: *"Search for open P1 bugs assigned to me"* ### Verification - [ ] Connector enabled and action restrictions set - [ ] Test user can search issues with JQL via Claude - [ ] Write actions respect configured restrictions - [ ] User cannot see issues from projects they lack access to --- ## 2.5 Confluence `Connector 5 of 7` · Read + Write · OAuth 2.0 (shared Atlassian auth) > **"Confluence write access creates and overwrites pages. Enable 'Needs approval' — not 'Always allow' — for write actions."** **Capabilities:** Search pages, read page content, create new pages, update existing pages, navigate spaces. ### Configuration **Step 1 of 3 — Enable and restrict** 1. Navigate to **Organization settings** → **Connectors** → enable **Confluence** 2. Configure action restrictions: | Action | Recommended setting | |--------|-------------------| | Search pages | Always allow | | Read content | Always allow | | List spaces | Always allow | | **Create pages** | **Needs approval** | | **Update pages** | **Needs approval** (overwrites content) | | **Add comments** | **Needs approval** | **Step 2 of 3 — User connection** Same OAuth flow as Jira (shared Atlassian authentication). **Step 3 of 3 — Verify** Test: *"Find the engineering onboarding guide in Confluence"* ### Verification - [ ] Connector enabled and action restrictions set - [ ] Test user can search and read pages - [ ] User cannot see pages in restricted spaces they don't have access to - [ ] Write actions require approval when triggered --- ## 2.6 Salesforce `Connector 6 of 7` · Read (+ Write via Agentforce) · OAuth 2.0 > **"Salesforce field-level security is enforced through the connector. If a user can't see a field in Salesforce, Claude can't see it either."** **Capabilities:** Query accounts, contacts, opportunities, cases. Search across CRM objects. Agentforce integration for agentic workflows. ### Prerequisites | # | Requirement | Provider | Location | |:-:|-------------|----------|----------| | 1 | Claude org Owner role | Claude admin | Admin Console | | 2 | Salesforce admin access | SFDC admin | Salesforce Setup | | 3 | Connected App configured | SFDC admin | Setup → App Manager | | 4 | Object access scope decided | Security + sales ops | Data access review | ### Architecture **Data flow:** User → *OAuth 2.0* → Claude MCP Server → *Salesforce REST API* → records back to user > **Access enforcement:** Salesforce sharing rules, profiles, and permission sets are fully enforced. Field-level security hides sensitive fields. Record-level access respects OWD, role hierarchy, and sharing rules. Agentforce partnership enables extended agentic capabilities. ### Configuration **Step 1 of 3 — Salesforce admin prep** 1. In Salesforce Setup → **App Manager** → create or configure a Connected App 2. Enable OAuth settings with appropriate scopes 3. Set permitted users (admin pre-authorized or user self-authorized) **Step 2 of 3 — Enable in Claude Admin Console** 1. Navigate to **Organization settings** → **Connectors** → enable **Salesforce** 2. Configure action restrictions (read-only recommended for initial rollout) **Step 3 of 3 — User connection and verification** 1. User connects via OAuth to their Salesforce org 2. Test: *"Show me the top 5 open opportunities by value"* 3. Verify user sees only records they have access to in Salesforce ### Verification - [ ] Connected App configured in Salesforce - [ ] Connector enabled in Claude Admin Console - [ ] Test user can query accounts/contacts/opportunities - [ ] User sees only records they have access to - [ ] Field-level security respected (sensitive fields hidden) --- ## 2.7 GitHub `Connector 7 of 7` · Read + Write · OAuth > **"The GitHub connector respects repository permissions. Private repos are invisible to users who don't have access."** **Capabilities:** Browse repositories, review pull requests, search code, manage issues, view commit history. ### Prerequisites | # | Requirement | Provider | Location | |:-:|-------------|----------|----------| | 1 | Claude org Owner role | Claude admin | Admin Console | | 2 | GitHub org admin access (for org install) | GitHub admin | GitHub Settings | | 3 | Decision: which repos to expose | Engineering lead | Repository inventory | ### Configuration **Step 1 of 3 — Enable and restrict** 1. Navigate to **Organization settings** → **Connectors** → enable **GitHub** 2. Configure action restrictions: | Action | Recommended setting | |--------|-------------------| | Browse repos, search code | Always allow | | View PRs and commits | Always allow | | **Create issues** | **Needs approval** or Blocked | | **Comment on PRs** | **Needs approval** | **Step 2 of 3 — User connection** 1. User connects via OAuth to their GitHub account 2. Selects which organizations/repos to grant access to 3. Claude inherits user's GitHub repository permissions **Step 3 of 3 — Verify** Test: *"Search for recent changes to the authentication module"* ### Verification - [ ] Connector enabled and action restrictions configured - [ ] Test user can search code and browse repositories - [ ] User cannot see private repos they don't have access to - [ ] Write actions respect configured restrictions --- # Part 3 — MCP Server Configuration `Part 3 of 5` | Previous: [Part 2](#part-2--web-connector-configuration) | Next: [Part 4](#part-4--enterprise-search) > **Key principle:** MCP servers extend Claude Code with custom tools, resources, and prompts. You control the infrastructure, the auth, and the scope. With that power comes responsibility for security and maintenance. ### 3.1 Protocol overview > **"MCP is a protocol, not a product. Claude discovers what a server can do, then calls it. The server does the actual work."** **The MCP protocol has four phases. Every server goes through this lifecycle:** > **Phase 1 · Initialize** > > Claude (Host) → MCP Client → `initialize` → MCP Server > > Server responds with its **capabilities** (what primitives it supports). Client sends `initialized` to confirm. > **Phase 2 · Discover** > > Claude → MCP Client → `tools/list` → MCP Server > > Server responds with **tool schemas** — names, descriptions, input parameters. Claude now knows what the server can do. > **Phase 3 · Invoke** > > User asks Claude something → Claude decides to use a tool → MCP Client → `tools/call` → MCP Server executes → **result** flows back to Claude → presented to user > **Phase 4 · Shutdown** > > Transport closes: `SIGTERM` for stdio, HTTP disconnect for Streamable HTTP. Server cleans up resources. **Three actors in every MCP interaction:** | Actor | Role | |-------|------| | **Claude (Host)** | Decides when to use tools, presents results to user | | **MCP Client** | Manages the protocol lifecycle, routes messages | | **MCP Server (your tool)** | Executes the actual work — API calls, file ops, computations | ### Transport options | Transport | How it works | Best for | Security | |-----------|-------------|----------|----------| | **stdio** | Client spawns server as subprocess. JSON-RPC over stdin/stdout. | Local dev, CLI tools, single-user | No network exposure — process isolation | | **Streamable HTTP** | Single endpoint. POST for requests, GET+SSE for streaming. | Remote servers, multi-user, production | HTTPS required. Validate Origin header. | ### 3.2 What you need before configuring any MCP server | # | Requirement | Details | |:-:|-------------|---------| | 1 | Claude Code installed | `curl -fsSL https://claude.ai/install.sh \| bash` | | 2 | Claude Code authenticated | Run `claude` → select enterprise SSO → authenticate | | 3 | Server source identified | Reference server (npm package) or custom (your code) | | 4 | Transport decided | stdio for local, Streamable HTTP for remote | | 5 | Credentials ready | API tokens, OAuth client IDs, env vars | | 6 | Scope decided | `local` (personal) · `project` (team) · `user` (all projects) | ### 3.3 Adding MCP servers > **Three methods exist.** Use CLI for quick setup. Use `.mcp.json` for team-shared config. Use `~/.claude.json` for personal defaults. **Method 1 — CLI commands** (interactive, good for initial setup) ```bash # HTTP transport (remote servers) claude mcp add --transport http # stdio transport (local subprocess servers) claude mcp add --transport stdio -- [args...] # With OAuth authentication claude mcp add --transport http my-server https://mcp.example.com \ --callback-port 9876 \ --client-id "my-client-id" # Import all servers from Claude Desktop config claude mcp add-from-claude-desktop # Add from raw JSON claude mcp add-json '{"command":"node","args":["server.js"],"env":{"TOKEN":"..."}}' ``` **Method 2 — Project config** (`.mcp.json` — check into git, shared with team) ```json { "mcpServers": { "server-name": { "command": "node", "args": ["dist/server.js"], "env": { "API_TOKEN": "${API_TOKEN}" } } } } ``` **Method 3 — User config** (`~/.claude.json` — personal, all projects) Same format as `.mcp.json`, but in your home directory. **Management commands:** ```bash claude mcp list # List all configured servers claude mcp get # Show server details claude mcp remove # Remove a server ``` ### 3.4 Reference server setup — step by step #### Filesystem server > **"Scoped file access. The paths you list are the only directories Claude can reach. Never add `/` or `~` as an allowed root."** ```bash claude mcp add --transport stdio filesystem -- \ npx -y @modelcontextprotocol/server-filesystem \ /Users/you/projects \ /Users/you/documents ``` **Resulting config:** ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects", "/Users/you/documents" ] } } } ``` **Verify:** Run `/mcp` in Claude Code → filesystem shows "connected" → ask *"List files in /Users/you/projects"* → confirm paths outside configured roots are rejected. > **Warning:** Misconfigured paths can expose sensitive files. Scope paths to the narrowest directory that covers your use case. #### Git server ```bash claude mcp add --transport stdio git -- \ npx -y @modelcontextprotocol/server-git ``` **Verify:** Navigate to a git repo → start Claude Code → ask *"Show me the last 5 commits"* #### Fetch server ```bash claude mcp add --transport stdio fetch -- \ npx -y @modelcontextprotocol/server-fetch ``` > **Warning:** Fetch retrieves content from URLs Claude chooses. Untrusted remote content can contain prompt injection. Use in controlled environments. #### Memory server ```bash claude mcp add --transport stdio memory -- \ npx -y @modelcontextprotocol/server-memory ``` > **Tip:** Review what data gets stored. Implement PII retention policies if using in an enterprise context. ### 3.5 Remote HTTP server configuration ```bash # Basic HTTP server claude mcp add --transport http internal-api https://mcp.internal.company.com/api # With bearer token authentication claude mcp add-json internal-api '{ "type": "http", "url": "https://mcp.internal.company.com/api", "headers": { "Authorization": "Bearer ${INTERNAL_API_TOKEN}" } }' # With OAuth (opens browser for auth flow) claude mcp add --transport http crm-server https://mcp.internal.company.com/crm \ --callback-port 9876 \ --client-id "claude-mcp-client" ``` **Team-shared remote config** (`.mcp.json`): ```json { "mcpServers": { "internal-api": { "type": "http", "url": "https://mcp.internal.company.com/api", "headers": { "Authorization": "Bearer ${INTERNAL_API_TOKEN}" } } } } ``` > **Important:** Never hardcode tokens. Use `${VAR_NAME}` syntax in configs and set actual values via shell environment or secrets manager. ### 3.6 Debugging MCP connections > **"When a server won't connect, work through these commands in order. Most issues are caught by `/doctor`."** **Diagnostic commands** (run inside Claude Code): | Command | What it shows | When to use | |---------|--------------|-------------| | `/mcp` | Connection status + tool counts per server | First check — is the server connected? | | `/doctor` | Full diagnostics — config, connectivity, auth | Server shows error in `/mcp` | | `/context` | Context window usage per MCP server | Responses are slow or truncated | | `claude --debug mcp` | Server stderr output in real time | Need to see server-side errors | **Standalone testing:** ```bash npx @modelcontextprotocol/inspector # Opens http://localhost:6274 # Test tools/list, tools/call independently of Claude ``` **Common issues:** | Symptom | Cause | Fix | |---------|-------|-----| | "Command not found" | Server package not installed | `npm install -g ` or use `npx -y` | | "ECONNREFUSED" | Server not running or wrong URL | Check URL, verify server process is up | | "401 Unauthorized" | Token expired or incorrect | Refresh token, check env var is set | | "Timeout" | Server too slow or network issue | Check API latency, increase timeout | | Too many tokens warning | Server returning too much data | Set `MAX_MCP_OUTPUT_TOKENS` env var | | Tools not appearing | Server not declaring tools | Test `tools/list` in MCP Inspector | --- # Part 4 — Enterprise Search `Part 4 of 5` | Previous: [Part 3](#part-3--mcp-server-configuration) | Next: [Part 5](#part-5--custom-mcp-server-development) > **Key principle:** Enterprise Search sits on top of your connectors. No connectors = nothing to search. Get Part 2 working first. ### 4.1 What Enterprise Search is > **"A unified, permission-aware search layer across all your organizational data. One question, all sources, cited answers."** Enterprise Search creates an **"Ask Your Org"** project in every user's sidebar. Users ask natural language questions and get answers drawn from Slack, Google Drive, Microsoft 365, Confluence, and other connected sources — simultaneously. Every answer includes source citations. ### 4.2 Architecture **How a query flows through Enterprise Search:** | Step | What happens | |:----:|-------------| | **1** | User asks a question in the **"Ask Your Org"** project (auto-created in sidebar) | | **2** | Search index receives the query | | **3** | Index checks the user's **permissions in each source system** | | **4** | Searches across **all connected sources simultaneously** — Slack, Google Drive, M365, Confluence | | **5** | Ranks, deduplicates, and returns results **with source citations** | **Connected data sources:** | Source | What's searchable | |--------|------------------| | **Slack** | Messages, threads, files | | **Google Drive** | Docs, sheets, slides | | **Microsoft 365** | SharePoint docs, OneDrive files, Outlook emails | | **Confluence** | Wiki pages, knowledge base articles | > **"Same query, different results."** Enterprise Search enforces permissions per user. User A (engineering) and User B (marketing) asking the same question get different answers based on what each can access in the source systems. ### 4.3 What you need before you start | # | Requirement | Provider | Why | |:-:|-------------|----------|-----| | 1 | Claude org Owner role | Claude admin | Only Owners can enable Enterprise Search | | 2 | At least 2 connectors working | Admin (from Part 2) | Search queries connected sources — no connectors = nothing to search | | 3 | Users individually connected to connectors | End users | Search respects per-user permissions via individual OAuth tokens | | 4 | Enterprise plan (for Drive Cataloging) | Procurement | Drive Cataloging is Enterprise-only; basic search works on Team+ | | 5 | Data classification review completed | Security | Decide which sources to include — not all should be searchable | | 6 | Test users with different permission levels | IT team | You must verify permission isolation works | ### 4.4 Configuration **Step 1 of 8 — Verify connector health** Before enabling Enterprise Search, confirm your connectors work: 1. Navigate to **Admin Console** → **Connectors** 2. Verify at least 2 connectors show as **Enabled** 3. Have at least one test user individually connected to each 4. Test each connector independently — can the user query data through it? > **Warning:** If any connector is broken, fix it first. Enterprise Search can't search what isn't connected. **Step 2 of 8 — Enable Enterprise Search** 1. Navigate to **Organization settings** → **Capabilities** 2. Find **Enterprise Search** → click **Enable** **Step 3 of 8 — Select data sources** Not all connectors should be in Enterprise Search. Select deliberately: | Source type | Examples | Include? | Rationale | |-------------|---------|----------|-----------| | **Document stores** | Google Drive, SharePoint, Confluence | Yes | Company docs, specs, policies — high signal | | **Chat platforms** | Slack, Teams | With caution | Useful for decisions/context but noisy | | **Issue trackers** | Jira | Consider excluding | Individual tickets are noisy in search | | **CRM** | Salesforce | Consider excluding | CRM data may not belong in general org search | | **Code repos** | GitHub | Consider excluding | Code search is better done in Claude Code | **Step 4 of 8 — Wait for index build** 1. Initial indexing can take **minutes to hours** depending on data volume 2. Monitor status in **Organization settings** → **Enterprise Search** 3. Do not proceed to testing until indexing shows complete **Step 5 of 8 — Verify "Ask Your Org" appears** 1. Log in as a test user (not admin) 2. Check the left sidebar — **"Ask Your Org"** project should be visible 3. If missing: verify the user has connected to at least one included connector **Step 6 of 8 — Test cross-source queries** | Test query | What you're validating | |------------|----------------------| | *"What is our policy on [topic]?"* | Document source search works | | *"What did the team decide about [topic] last week?"* | Chat source search works | | *"Find the [specific document name]"* | Citation and direct linking work | | *"Summarize our approach to [topic]"* | Cross-source aggregation works | **Step 7 of 8 — Test permission isolation** > **This is the most important test.** If it fails, stop the rollout. 1. **User A** has access to: #engineering (Slack), Engineering folder (Drive) 2. **User B** has access to: #marketing (Slack), Marketing folder (Drive) 3. Both ask: *"What are our Q3 priorities?"* 4. **User A** should see engineering priorities only 5. **User B** should see marketing priorities only 6. **Neither** should see the other's restricted documents **Step 8 of 8 — Enable Drive Cataloging** (Enterprise plan only) 1. In Enterprise Search settings, enable **Drive Cataloging** 2. Indexes Google Docs up to 10MB with RAG-based retrieval 3. Periodic re-indexing keeps content current 4. Test: delete a file from Drive → wait 1 hour → verify it no longer appears in search ### 4.5 Ongoing administration | Task | Frequency | |------|-----------| | Review included sources | Monthly | | Check indexing health | Weekly | | Collect search quality feedback | Monthly | | Permission isolation spot-check | Quarterly | | Add new connectors to search | As needed | ### 4.6 Troubleshooting | Symptom | Cause | Resolution | |---------|-------|------------| | "Ask Your Org" not visible | User hasn't connected to any included connector | Have user connect to at least one source | | No results for known documents | Indexing still in progress | Check index status, wait for completion | | Stale results after doc update | Re-index cycle hasn't run | Wait for periodic re-index | | User sees restricted documents | Source system permissions misconfigured | Audit permissions in the source system — not a Claude issue | | Search is slow | Large index with many sources | Reduce included sources or check for indexing errors | | Drive Cataloging not updating | File exceeds 10MB limit | Only Google Docs up to 10MB are indexed | ### Verification - [ ] At least 2 connectors enabled and healthy - [ ] Enterprise Search enabled in Organization settings → Capabilities - [ ] Data sources deliberately selected - [ ] Index build completed for all selected sources - [ ] "Ask Your Org" project visible in test user's sidebar - [ ] Cross-source query returns results with citations - [ ] Permission isolation tested — User A cannot see User B's restricted documents - [ ] Permission isolation tested — User B cannot see User A's restricted documents - [ ] Drive Cataloging enabled and indexing confirmed (Enterprise plan) - [ ] De-indexing tested — deleted file removed within 1 hour --- # Part 5 — Custom MCP Server Development `Part 5 of 5` | Previous: [Part 4](#part-4--enterprise-search) > **Key principle:** Build a custom server when no pre-built option covers your use case. Design before you code. Test with the Inspector before deploying. Govern like any production service. ### 5.1 Should you build a custom server? > **"If a pre-built option exists and meets your security requirements, use it. Custom servers are powerful but carry maintenance burden."** Build custom when you need: - Access to an internal API behind your firewall - Custom authorization logic (per-user, per-team scoping) - Data transformation or DLP filtering before returning results - Workflow orchestration across multiple internal systems - Compliance controls that generic servers can't enforce ### 5.2 Prerequisites | # | Requirement | Provider | |:-:|-------------|----------| | 1 | Internal API documentation (endpoints, auth, rate limits) | API team | | 2 | SDK choice: TypeScript (`@modelcontextprotocol/sdk`) or Python (`mcp` / FastMCP) | Engineering | | 3 | Transport choice: stdio (local) or Streamable HTTP (remote) | Architecture | | 4 | Auth strategy: how Claude authenticates to your server | Security team | | 5 | Hosting environment decided (local, container, cloud) | Platform team | | 6 | MCP governance approval from admin/security | Admin | ### 5.3 Architecture **Choose your transport based on who needs access:** > **Option A · stdio** — Local, single-user > > Claude Code **spawns** your server as a subprocess. Communication via **stdin/stdout** (JSON-RPC). Server **dies** when the Claude session ends. > > **Flow:** Claude Code → *spawns process* → MCP Server → *HTTPS* → Internal API → response back > > No network exposure. Process isolation. Best for: **local dev, CLI tools, single-developer use.** > **Option B · Streamable HTTP** — Remote, multi-user > > Your server is **hosted on your infrastructure** (container, VM, serverless). Claude communicates via **HTTPS** (POST for requests, GET+SSE for streaming). An **auth layer** (OAuth 2.1, API keys, or mTLS) protects the server. > > **Flow:** Claude Code or claude.ai → *HTTPS POST* → MCP Server (your infra) → *HTTPS* → Internal API → response back via SSE > > HTTPS required. Horizontal scaling. Best for: **team-wide tools, production services, multi-user.** ### 5.4 Phase A — Design (1–2 days) > **"Think in user outcomes, not API endpoints. 'A developer needs to look up a ticket while debugging' — not 'wrap GET /tickets'."** **Step 1 — Map outcomes to primitives** | User outcome | MCP primitive | Name | Why | |-------------|---------------|------|-----| | Look up a ticket by ID | **Tool** | `get_ticket` | Requires parameter — tools handle actions | | See all open P0 incidents | **Tool** | `list_incidents` | Requires filtering | | Read the API schema docs | **Resource** | `docs://api-schema` | Static content, no parameters | | Start an incident response | **Prompt** | `incident-response` | Multi-step template workflow | **Step 2 — Design strict schemas** > **"Every field gets a description. Every required field is marked required. Enums for fixed values. Patterns for formatted strings."** ```json { "name": "get_ticket", "description": "Retrieve a support ticket by its ID. Returns summary, status, assignee, priority, and recent comments.", "inputSchema": { "type": "object", "properties": { "ticketId": { "type": "string", "description": "Ticket ID in format TEAM-1234", "pattern": "^[A-Z]+-[0-9]+$" } }, "required": ["ticketId"] } } ``` **Step 3 — Write excellent tool descriptions** Tool descriptions are the prompts Claude reads to decide when and how to use each tool: | Weak | Strong | |------|--------| | "Gets a ticket" | "Retrieve a support ticket by its ID. Returns summary, status, assignee, priority, and the 5 most recent comments. Use when the user references a ticket ID or asks about a specific support issue." | | "Search" | "Search open support tickets by keyword, status, priority, or assignee. Returns up to 20 results sorted by last updated. Use when the user asks about tickets matching criteria rather than a specific ID." | ### 5.5 Phase B — Implement (2–5 days) #### TypeScript — full working server ```bash mkdir my-mcp-server && cd my-mcp-server npm init -y npm install @modelcontextprotocol/sdk zod npm install -D typescript @types/node npx tsc --init ``` **`src/server.ts`:** ```typescript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; const API_BASE = process.env.API_BASE_URL ?? "https://api.internal.example"; const API_TOKEN = process.env.API_TOKEN; if (!API_TOKEN) { console.error("API_TOKEN environment variable is required"); process.exit(1); } async function apiCall(path: string): Promise { const res = await fetch(`${API_BASE}${path}`, { headers: { Authorization: `Bearer ${API_TOKEN}` }, signal: AbortSignal.timeout(30_000), }); if (!res.ok) throw new Error(`API error: ${res.status} ${res.statusText}`); return res.json(); } const server = new McpServer({ name: "internal-ticketing", version: "1.0.0" }); server.tool( "get_ticket", "Retrieve a support ticket by ID. Returns summary, status, assignee, priority, and recent comments.", { ticketId: z.string().regex(/^[A-Z]+-[0-9]+$/).describe("Ticket ID, e.g. ENG-1234") }, async ({ ticketId }) => { try { const ticket = await apiCall(`/tickets/${ticketId}`); return { content: [{ type: "text", text: JSON.stringify(ticket, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Failed: ${error instanceof Error ? error.message : "Unknown"}` }], isError: true, }; } } ); server.tool( "search_tickets", "Search open support tickets by keyword, status, or assignee. Max 20 results sorted by last updated.", { query: z.string().describe("Search keyword"), status: z.enum(["open", "in_progress", "resolved", "closed"]).optional(), assignee: z.string().optional().describe("Filter by assignee email"), limit: z.number().min(1).max(50).default(20), }, async ({ query, status, assignee, limit }) => { const params = new URLSearchParams({ q: query, limit: String(limit) }); if (status) params.set("status", status); if (assignee) params.set("assignee", assignee); try { const results = await apiCall(`/tickets/search?${params}`); return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Search failed: ${error instanceof Error ? error.message : "Unknown"}` }], isError: true, }; } } ); server.resource("api-docs", "docs://api-schema", async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: "# Internal Ticketing API\n\n- GET /tickets/:id\n- GET /tickets/search?q=...\n- POST /tickets\n- PATCH /tickets/:id", }], })); const transport = new StdioServerTransport(); await server.connect(transport); ``` **Build and test:** ```bash npx tsc API_TOKEN=test-token npx @modelcontextprotocol/inspector node dist/server.js # Opens http://localhost:6274 — test each tool interactively ``` #### Python — full working server ```bash mkdir my-mcp-server && cd my-mcp-server python -m venv .venv && source .venv/bin/activate pip install mcp httpx ``` **`server.py`:** ```python import json, os import httpx from mcp.server.fastmcp import FastMCP API_BASE = os.environ.get("API_BASE_URL", "https://api.internal.example") API_TOKEN = os.environ["API_TOKEN"] client = httpx.Client( base_url=API_BASE, headers={"Authorization": f"Bearer {API_TOKEN}"}, timeout=30.0, ) mcp = FastMCP("internal-ticketing") @mcp.tool() def get_ticket(ticket_id: str) -> str: """Retrieve a support ticket by ID. Returns summary, status, assignee, priority, and recent comments. Format: TEAM-1234.""" resp = client.get(f"/tickets/{ticket_id}") resp.raise_for_status() return json.dumps(resp.json(), indent=2) @mcp.tool() def search_tickets(query: str, status: str | None = None, assignee: str | None = None, limit: int = 20) -> str: """Search open support tickets by keyword, status, or assignee. Returns up to `limit` results sorted by last updated.""" params = {"q": query, "limit": limit} if status: params["status"] = status if assignee: params["assignee"] = assignee resp = client.get("/tickets/search", params=params) resp.raise_for_status() return json.dumps(resp.json(), indent=2) @mcp.resource("docs://api-schema") def api_docs() -> str: """Internal Ticketing API documentation.""" return "# Ticketing API\n- GET /tickets/:id\n- GET /tickets/search\n- POST /tickets" if __name__ == "__main__": mcp.run(transport="stdio") ``` **Test:** ```bash API_TOKEN=test-token npx @modelcontextprotocol/inspector python server.py ``` #### Streamable HTTP (remote deployment) > **"Use Streamable HTTP when the server needs to serve multiple users or run on shared infrastructure."** **TypeScript:** ```typescript import express from "express"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; const app = express(); app.use(express.json()); app.all("/mcp", async (req, res) => { const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => crypto.randomUUID(), }); const server = new McpServer({ name: "internal-ticketing", version: "1.0.0" }); // Register tools here (same as stdio example) await server.connect(transport); await transport.handleRequest(req, res); }); app.listen(3001, () => console.log("MCP server on http://localhost:3001/mcp")); ``` **Python:** ```python if __name__ == "__main__": mcp.run(transport="streamable-http", host="0.0.0.0", port=3001) ``` ### 5.6 Phase C — Harden (1–2 days) > **"Every item below is a production gate. Ship none of them and you'll get paged. Ship all of them and you'll sleep."** **Input validation** - [ ] All parameters validated with Zod (TS) or Pydantic (Python) - [ ] String inputs bounded by max length - [ ] Numeric inputs bounded by min/max - [ ] Enum values for constrained fields - [ ] Reject unexpected fields (strict mode) **Rate limiting and timeouts** - [ ] Per-tool rate limits (e.g., 60 calls/min for search) - [ ] Global rate limit for the server - [ ] API call timeout at 30s (`AbortSignal` / `httpx.timeout`) - [ ] Total tool execution timeout at 60s - [ ] Graceful error on timeout (not stack trace) **Secrets and error handling** - [ ] All credentials via environment variables - [ ] No secrets in code, configs, or logs - [ ] Server refuses to start if required env vars are missing - [ ] `isError: true` flag on all error responses - [ ] Clear, actionable error messages (no internal stack traces) - [ ] Structured logging with request/trace IDs **Output safety** - [ ] Response size bounded (avoid returning 100K rows) - [ ] PII filtering if applicable - [ ] Stable, deterministic output format ### 5.7 Phase D — Test (1–2 days) **Step 1 — Unit tests** ```bash # TypeScript # Python npx vitest run pytest tests/ ``` **Step 2 — MCP Inspector** (interactive protocol testing) ```bash npx @modelcontextprotocol/inspector node dist/server.js # Opens http://localhost:6274 ``` | Test | Expected result | |------|----------------| | `tools/list` | All tools appear with correct names and schemas | | `tools/call` — valid input | Correct data returned | | `tools/call` — invalid input | `isError: true` with clear message | | `tools/call` — missing required field | Validation error, not crash | | `tools/call` — API unreachable | `isError: true` with timeout message | | `resources/list` | Resources appear with correct URIs | | `resources/read` | Expected content returned | **Step 3 — Integration test with Claude** ```bash claude mcp add --transport stdio my-api -- node dist/server.js claude ``` ``` /mcp # Verify connection > Look up ticket ENG-4521 > Find all open P0 incidents assigned to alice@company.com > Show me the API documentation ``` > **Verify:** Claude selects the right tool, extracts parameters correctly, and renders clean output. Error cases produce helpful messages. **Step 4 — Security review** - [ ] No credentials in source code (grep for tokens, passwords, keys) - [ ] Input validation cannot be bypassed - [ ] Server cannot access data outside its intended scope - [ ] Logs don't contain sensitive data - [ ] Complies with org MCP governance policy ### 5.8 Phase E — Deploy and distribute **Option A — Project-level** (`.mcp.json`, team-shared via git): ```json { "mcpServers": { "internal-ticketing": { "command": "node", "args": ["dist/server.js"], "env": { "API_TOKEN": "${TICKETING_API_TOKEN}" } } } } ``` > Each developer sets `TICKETING_API_TOKEN` in their shell environment. **Option B — Managed settings** (org-wide, admin-controlled): ```json { "mcpServers": { "allowManagedMcpServersOnly": false, "allowedMcpServers": ["internal-ticketing", "filesystem", "git"] } } ``` **Option C — Remote HTTP** (centrally hosted): ```bash claude mcp add --transport http internal-ticketing https://mcp.internal.company.com/ticketing ``` ### 5.9 Governance lifecycle > **"Treat custom MCP servers like any production service: approved, deployed, monitored, maintained, reviewed."** | Phase | Actions | Cadence | |-------|---------|---------| | **Approval** | Security review, document purpose/tools/auth/data, add to approved list | Before deployment | | **Deployment** | Distribute via `.mcp.json` or managed settings, document setup for developers | Once | | **Monitoring** | Review MCP audit logs, monitor health/errors/latency, alert on anomalies | Weekly | | **Maintenance** | Rotate credentials, update SDK dependencies, re-review when tools change | Quarterly | | **Review** | Is the server still needed? Tools aligned with needs? Any incidents? | Quarterly | ### Verification - [ ] Design doc completed: user outcomes, tool schemas, auth model - [ ] Server implemented with at least one tool and one resource - [ ] Input validation on all parameters - [ ] Error handling returns `isError: true` with clear messages - [ ] Secrets via env vars only - [ ] Rate limiting and timeouts in place - [ ] MCP Inspector tests passing for all tools - [ ] Claude integration test — tools invoked correctly via natural language - [ ] Security review completed per org governance policy - [ ] Server added to approved MCP list - [ ] Distributed to team - [ ] Setup instructions documented - [ ] Monitoring configured - [ ] Quarterly review scheduled --- ## Appendix — Universal integration checklist Use for any new integration rollout: **Pre-configuration** - [ ] Integration type identified (web connector vs MCP server) - [ ] Security/compliance review completed - [ ] Data classification of accessible data documented - [ ] Access scope defined (which users, which data) - [ ] Credentials/OAuth app created - [ ] Rollback plan documented **Configuration** - [ ] Connector/server enabled in appropriate config - [ ] Action restrictions set (read-only first) - [ ] Service-specific prerequisites completed - [ ] Test user connected and authenticated - [ ] Verification tests passed **Post-configuration** - [ ] Approved integrations list updated - [ ] Users notified of new integration - [ ] Training delivered on usage and limitations - [ ] Monitoring/alerting configured - [ ] Review date scheduled (30 days)

MCP & connector configuration: step-by-step training