Skip to content

Instantly share code, notes, and snippets.

@jrepp

jrepp/ClaudeCode_AgentCore_DevGuide.md

Created October 6, 2025 05:41
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jrepp/a5f4a9f0e4d952db19297294c61eadb2 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jrepp/a5f4a9f0e4d952db19297294c61eadb2 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
ClaudeCode_AgentCore_DevGuide.md 
# Claude Code Developer Guide: Complete Setup with MCP Integrations

A minimal guide to setting up Claude Code with AgentCore, GitHub, semantic search, and essential MCP servers for maximum productivity.

---

## Table of Contents

- [Prerequisites](#prerequisites)
- [Core Setup](#core-setup)
- [GitHub Integration](#github-integration)
- [Context7 Semantic Search](#context7-semantic-search)
- [Language Support](#language-support)
- [AWS Bedrock AgentCore](#aws-bedrock-agentcore)
- [Essential MCP Servers](#essential-mcp-servers)
- [Advanced Configuration](#advanced-configuration)
- [Verification & Testing](#verification--testing)
- [Pro Tips](#pro-tips)

---

## Prerequisites

```bash
# Install uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Python
uv python install 3.10

# Install Claude Code
# Visit: https://docs.claude.com/en/docs/claude-code/overview

# Authenticate
claude auth login

Core Setup

Install Base Dependencies

# AWS credentials (if using AgentCore)
aws configure

# GitHub token
export GITHUB_TOKEN=ghp_your_token_here

# AgentCore toolkit (optional)
pip install bedrock-agentcore-starter-toolkit

MCP Configuration File

Location: ~/.claude/mcp.json

Create base structure:

{
  "mcpServers": {}
}

GitHub Integration

1. Generate Personal Access Token

  • Go to GitHub Settings → Developer Settings → Personal Access Tokens → Tokens (classic)
  • Generate token with: repo, read:org, read:user scopes

2. Add to MCP Config

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

3. Quick Install via CLI

claude mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_TOKEN \
  -- npx -y @modelcontextprotocol/server-github

Usage Examples

claude
# Then in Claude Code:
# "List my recent pull requests"
# "Create an issue in owner/repo about X"
# "Show me the diff for PR #123"

Context7 Semantic Search

1. Setup Upstash Account

  • Visit: https://upstash.com
  • Create Redis database
  • Get UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN

2. Add to MCP Config

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "env": {
        "UPSTASH_REDIS_REST_URL": "https://your-redis.upstash.io",
        "UPSTASH_REDIS_REST_TOKEN": "your-token"
      }
    }
  }
}

3. Quick Install

claude mcp add context7 -- npx -y @upstash/context7-mcp@latest

Usage Examples

# "Search the codebase for authentication logic"
# "Find all functions that handle user data"
# "Show me files related to payment processing"

Language Support

Built-in Support

Claude Code has native understanding for:

  • Go
  • Python
  • Rust
  • TypeScript/JavaScript
  • And 40+ other languages

Verify Tools Installed

# Go
go version

# Python
python3 --version

# Rust
rustc --version
cargo --version

No LSP configuration needed - Claude Code understands these languages natively.

AWS Bedrock AgentCore

1. Install AgentCore MCP Server

{
  "mcpServers": {
    "agentcore": {
      "command": "uvx",
      "args": ["awslabs.bedrock-agentcore-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "your-profile",
        "AWS_REGION": "us-west-2",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

2. Deploy Agent Workflow

# Start Claude Code
claude

# Natural language deployment:
# "Transform my agent in agent.py to work with AgentCore Runtime"
# "Deploy it to my AWS account"
# "Test the deployment with a sample request"

3. Manual Deployment (Alternative)

# Configure agent
agentcore configure --entrypoint agent.py

# Deploy
agentcore deploy

# Test
agentcore invoke --payload '{"prompt": "hello"}'

Essential MCP Servers

1. Sequential Thinking (Critical for Complex Tasks)

{
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
  }
}

Why: Forces step-by-step reasoning. Dramatically improves multi-step refactoring quality.

claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking

2. Brave Search (Real-time Documentation)

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "BSA..."
    }
  }
}

Why: Latest API docs, framework updates, library changes.

Get API key: https://brave.com/search/api/

claude mcp add brave --env BRAVE_API_KEY=$BRAVE_KEY \
  -- npx -y @modelcontextprotocol/server-brave-search

3. Puppeteer (Visual Debugging)

{
  "puppeteer": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
  }
}

Why: Screenshots, UI comparisons, visual iteration. Essential for frontend work.

claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

4. Memory (Cross-Session Context)

{
  "memory": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-memory"]
  }
}

Why: Remembers project conventions, patterns, decisions across sessions.

claude mcp add memory -- npx -y @modelcontextprotocol/server-memory

5. Database Access (Postgres Example)

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/db"
    }
  }
}

Why: Direct schema inspection, query generation, migrations.

claude mcp add postgres --env POSTGRES_CONNECTION_STRING=$DB_URL \
  -- npx -y @modelcontextprotocol/server-postgres

6. Sentry (Production Debugging)

{
  "sentry": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sentry"],
    "env": {
      "SENTRY_AUTH_TOKEN": "your-token",
      "SENTRY_ORG": "your-org"
    }
  }
}

Why: Pull errors, stack traces, debug production issues directly.

7. Slack (Team Context)

{
  "slack": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "xoxb-...",
      "SLACK_TEAM_ID": "T..."
    }
  }
}

Why: Design decisions, channel context, automated updates.

Advanced Configuration

Project-Level MCP Servers

Create .mcp.json in your project root:

{
  "mcpServers": {
    "project-specific": {
      "command": "npx",
      "args": ["-y", "your-custom-server"],
      "env": {
        "PROJECT_VAR": "value"
      }
    }
  }
}

Scope precedence: Project .mcp.json > User ~/.claude/mcp.json

Skip Permissions for Trusted Tools

# Start Claude Code without permission prompts
claude --dangerously-skip-permissions

# Or set per-session in Claude Code:
# /permissions
# Add tools to allowlist: Edit, Bash, etc.

Environment Variable Management

Create .env file:

GITHUB_TOKEN=ghp_...
BRAVE_API_KEY=BSA...
UPSTASH_REDIS_REST_URL=https://...
UPSTASH_REDIS_REST_TOKEN=...
AWS_PROFILE=default

Reference in MCP config:

{
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
  }
}

Complete MCP Configuration Example

~/.claude/mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
      }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "env": {
        "UPSTASH_REDIS_REST_URL": "https://...",
        "UPSTASH_REDIS_REST_TOKEN": "..."
      }
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA..."
      }
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "agentcore": {
      "command": "uvx",
      "args": ["awslabs.bedrock-agentcore-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-west-2",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Verification & Testing

List Configured Servers

claude mcp list

Expected output:

github          ✓ Running
context7        ✓ Running
sequential-thinking ✓ Running
brave-search    ✓ Running
...

Test Individual Servers

# Get server details
claude mcp get github

# Remove server
claude mcp remove github

# Re-add
claude mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_TOKEN \
  -- npx -y @modelcontextprotocol/server-github

Manual Server Testing

# Test MCP server directly (15s timeout)
timeout 15s uvx awslabs.bedrock-agentcore-mcp-server@latest 2>&1 || echo "OK"

In Claude Code

claude

# Then test:
# "What MCP servers are available?"
# "List my GitHub repositories"
# "Search the codebase for error handling"
# "Take a screenshot of localhost:3000"

Pro Tips

Performance Optimization

  1. Start minimal: 3-4 servers max. Add more only when needed.
  2. Remove @latest suffix for faster startup (manually update with uvx tool@latest): 
    "args": ["awslabs.bedrock-agentcore-mcp-server"]
  3. Clear UV cache periodically: 
    uv cache clean awslabs.bedrock-agentcore-mcp-server

Workflow Best Practices

  1. Use /clear frequently - Start fresh for new tasks to avoid token bloat
  2. Project-specific .mcp.json - Check into git for team consistency
  3. Custom slash commands - Store templates in .claude/commands/
  4. Enable MCP debug mode: 
    claude --mcp-debug

Recommended Server Combinations

Frontend Developer:

github + puppeteer + brave-search + sequential-thinking

Backend Developer:

github + postgres + sentry + memory + sequential-thinking

Full-Stack + AWS:

github + agentcore + brave-search + puppeteer + sequential-thinking

Data Engineer:

postgres + context7 + sequential-thinking + memory

Troubleshooting

Server won't start:

# Check logs
claude mcp get <server-name>

# Test manually
npx -y @modelcontextprotocol/server-github

# Verify environment variables
echo $GITHUB_TOKEN

Permission prompts too frequent:

# Use dangerously-skip-permissions
claude --dangerously-skip-permissions

# Or configure per-tool in /permissions

Token limits with many servers:

# Increase MCP output limit
export MAX_MCP_OUTPUT_TOKENS=50000
claude

Quick Start Commands

# Core productivity stack (copy-paste)
claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking
claude mcp add brave --env BRAVE_API_KEY=$BRAVE_KEY -- npx -y @modelcontextprotocol/server-brave-search
claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer
claude mcp add memory -- npx -y @modelcontextprotocol/server-memory
claude mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_TOKEN -- npx -y @modelcontextprotocol/server-github

# Verify
claude mcp list

# Start coding
claude --dangerously-skip-permissions

Resources

License

This guide is provided as-is. Refer to individual tool licenses for usage terms.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment