basecamp-mcp-server/Claude_MCP_integration_instructions.md

Integrating Your Basecamp MCP Server with Anthropic Claude

This guide explains how to connect your custom Basecamp MCP (Model Context Protocol) server to Anthropic's Claude AI, enabling Claude to use your Basecamp tools. This process leverages Claude's "Custom Integrations" feature for "Remote MCP servers."

Prerequisites:

• A paid Anthropic Claude plan (Max, Team, or Enterprise) is required to use custom integrations with remote MCP servers.
• Your Basecamp MCP server code (including mcp_server.py, composio_integration.py, oauth_app.py, etc.).
• Basecamp application credentials (Client ID, Client Secret).

---

Phase 1: Server Preparation & Pre-authentication

1. Environment Setup:

   • Ensure you have Python (3.10+ recommended).
   • Open a terminal in your project's root directory.
   • Create and activate a Python virtual environment:

     python -m venv venv
     source venv/bin/activate  # On Windows: venv\Scripts\activate
     

   • Install necessary Python packages:

     pip install -r requirements.txt requests python-dotenv flask-cors
     

2. Configuration (.env file):

   • Ensure your .env file in the project root is correctly populated with your Basecamp App credentials and server settings. Create one if it doesn't exist (e.g., from a .env.example):

     BASECAMP_ACCOUNT_ID=your_basecamp_account_id
     BASECAMP_CLIENT_ID=your_basecamp_app_client_id
     BASECAMP_CLIENT_SECRET=your_basecamp_app_client_secret
     BASECAMP_REDIRECT_URI=http://localhost:8000/callback # Used by oauth_app.py
     USER_AGENT=YourAppName/1.0 (yourcontact@example.com) # Or any valid User-Agent
     MCP_PORT=5001 # Default port for your MCP server
     FLASK_DEBUG=False # Recommended for anything beyond local testing
     

3. Pre-authenticate with Basecamp (Crucial):

   • Before exposing your MCP server publicly for Claude, you must obtain valid Basecamp OAuth tokens and store them locally for the server to use.
   • Run the standalone OAuth helper application provided in your repository:

     (venv) $ python oauth_app.py
     

   • This will typically start a local web server on http://localhost:8000.
   • Open http://localhost:8000 in your web browser.
   • Follow the on-screen prompts to authenticate with your Basecamp account and authorize your application.
   • Upon successful authentication, oauth_app.py will create/update a file named oauth_tokens.json in your project root. This file contains the access_token and refresh_token that mcp_server.py will use.
   • Why this is important: This step ensures your MCP server is already authenticated with Basecamp. When Claude connects, the server can directly use these stored tokens (and refresh them as needed using refresh_oauth_token) without requiring Claude to handle a redirect to a localhost OAuth URL, which wouldn't work for a remote service.

4. Run Your MCP Server Locally (for initial verification):

   • Once oauth_tokens.json exists and is populated, start your main MCP server:

     (venv) $ python mcp_server.py
     

   • The server should now be running, typically at http://localhost:5001. You can test basic health: curl http://localhost:5001/health.

---

Phase 2: Making Your MCP Server Publicly Accessible

Claude's servers need to be able to reach your MCP server over the internet.

1. Using ngrok (Recommended for Development/Testing):

   • Download and install ngrok from ngrok.com.
   • Authenticate ngrok if it's your first time (see ngrok's documentation).
   • With your MCP server running locally (from Phase 1, Step 4), open a new terminal window and run:

     ngrok http 5001
     

     (Replace 5001 if your MCP_PORT is different).
   • ngrok will display a public HTTPS URL (e.g., https://<unique-string>.ngrok-free.app). Copy this HTTPS URL. This will be your YOUR_PUBLIC_MCP_SERVER_URL used when configuring Claude.

2. Production Deployment (Advanced):

   • For a permanent or production setup, you would deploy mcp_server.py as a WSGI application (e.g., using Gunicorn behind an Nginx reverse proxy) to a cloud provider (AWS, Google Cloud, Azure, Heroku, etc.).
   • Ensure your production deployment is configured with HTTPS.

---

Phase 3: Adding the MCP Server to Claude.ai

Note: This requires a paid Claude plan (Claude Max, Team, or Enterprise).

1. Navigate to Claude.ai Settings:

   • Log in to your Claude.ai account.
   • For Claude Max users: Go to Settings > Profile.
   • For Claude Team or Enterprise users: Go to Settings > Integrations (for Teams) or Settings > Data management (for Enterprise). Note: Only Primary Owners or Owners can add new integrations on Team/Enterprise plans.

2. Add Custom Integration:

   • Look for a section titled "Integrations" or similar.
   • Click on an option like "Add more," "Add custom integration," or "Connect new integration."
   • You will be prompted to enter your "integration's remote MCP server URL" (or similar wording).

3. Provide Server URL and Configure:

   • Enter the public HTTPS URL of your MCP server obtained in Phase 2 (e.g., your ngrok URL like https://<unique-string>.ngrok-free.app).
   • Claude will attempt to connect to this URL to:
     • Discover available tools: It typically looks for a schema endpoint. Your server provides this at /composio/schema (e.g., https://<your_url>/composio/schema).
     • Check authentication status: It uses /composio/check_auth. Because you pre-authenticated in Phase 1, this endpoint should return {"authenticated": True}, and Claude should not need to initiate a new OAuth flow with Basecamp.
   • Follow any on-screen prompts in the Claude interface to complete the configuration and save the integration.

---

Phase 4: Using the Integration in Claude

1. Enable Tools in Chat:

   • Once the integration is successfully added, you can enable it and its specific tools (e.g., GET_PROJECTS, CREATE_COMMENT, as defined in your composio_integration.py) within a Claude chat.
   • Look for a "Search and tools" menu (often a briefcase icon or similar) in the chat interface. From here, you can toggle your Basecamp integration and select/deselect individual tools for the current conversation.

2. Interact with Claude:

   • You can now ask Claude to perform actions using your Basecamp tools. For example:
     • "Claude, what are my current projects in Basecamp?"
     • "Can you get the to-do lists for the 'Marketing Campaign' project?"
     • "Create a new to-do item in the 'Website Launch' list with the content 'Finalize homepage design'."
   • Claude will communicate with your MCP server (via the public URL) to execute these actions.

---

Important Considerations & Potential Adjustments

1. Schema Endpoint (/composio/schema):

   • Your mcp_server.py uses composio_integration.py which exposes tool schemas at the /composio/schema path. Claude's remote MCP integration feature should discover this.
   • The schema format in composio_integration.py uses a "parameters" key for defining tool inputs. Standard Claude tool use often refers to an "input_schema" key. While MCP is an open standard, if Claude has trouble understanding your tool parameters, you might need to modify composio_integration.py to rename "parameters" to "input_schema" within the get_schema() function for each tool.

2. Tool Execution Endpoint (/composio/tool):

   • Tool execution requests from Claude will be directed to the /composio/tool endpoint on your server.

3. Security:

   • Public Endpoint: Remember that your ngrok URL (or production URL) makes your MCP server publicly accessible. While oauth_tokens.json is not directly exposed, the server itself is. For production, implement robust security measures:
     • Ensure HTTPS is enforced.
     • Consider adding an API key or other authentication layer directly to your MCP server endpoints (/composio/schema, /composio/tool) to prevent unauthorized access. The composio_integration.py file has a placeholder for checking an X-Composio-API-Key header; you could adapt this.
   • Permissions: Be mindful of the permissions granted to your Basecamp application. The tools will operate with these permissions.
   • Anthropic's Guidance: Always review Anthropic's security and privacy considerations for custom integrations.

4. Logging and Debugging:

   • Your mcp_server.py includes logging. Monitor these logs (e.g., improved_mcp_server.log and console output) on your server when setting up and testing the integration to diagnose any issues.
   • If using ngrok, its web interface (http://localhost:4040 by default) provides a request inspector which is very helpful for debugging.

5. Firewall/Network:

   • If deploying to a server with a firewall, ensure the port your MCP server is running on (e.g., 5001) allows inbound HTTPS traffic.

By following these steps, you should be able to successfully integrate your Basecamp MCP server with Anthropic Claude, empowering Claude with your custom Basecamp functionalities.