MCP-LIVEOPS

LiveOps Agent --- MCP-Based Real-Time API Intelligence

MCP-LIVEOPS is a mini industry-style Agentic AI project demonstrating how Claude can use the Model Context Protocol (MCP) to retrieve real-time cryptocurrency market data from CoinGecko and produce a grounded final response.

Project Objective

The project demonstrates this complete vertical slice:

User
 ↓
Claude
 ↓
Tool Selection
 ↓
MCP Client
 ↓
MCP Server
 ↓
CoinGecko Live API
 ↓
Structured Market Data
 ↓
Claude
 ↓
Final Answer

The main technologies demonstrated are:

• Claude / Anthropic
• Model Context Protocol (MCP)
• Agentic tool calling
• CoinGecko live API
• Pydantic
• Python 3.12
• UV
• Pytest
• Ruff
• Dependency injection
• Git/GitHub
• Docker / CI foundation

The project intentionally remains small and focused. It does not introduce RAG, vector databases, multi-agent systems, Kubernetes, or unnecessary cloud infrastructure.

---

1. Problem Statement

Traditional LLM applications often embed external API calls directly inside application logic.

MCP introduces a standardized tool boundary:

Claude
 ↓
MCP Tool
 ↓
Provider
 ↓
External API

This project demonstrates that architecture with a real cryptocurrency market-data API.

---

2. Use Case

Example user request:

What are the current Bitcoin and Ethereum prices?

Claude can select:

get_crypto_prices

with arguments such as:

{
  "coin_ids": ["bitcoin", "ethereum"],
  "currency": "usd"
}

The tool calls CoinGecko, returns structured market data, and the result is supplied back to Claude for the final response.

---

3. Architecture

                         ┌──────────────┐
                         │     User     │
                         └──────┬───────┘
                                │
                                ▼
                         ┌──────────────┐
                         │    Claude    │
                         │ Tool Select  │
                         └──────┬───────┘
                                │
                             tool_use
                                │
                                ▼
                       ┌─────────────────┐
                       │  LiveOpsAgent   │
                       │  Orchestration  │
                       └────────┬────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │ MCP Client      │
                       │ McpClientAdapter │
                       └────────┬────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │   MCP Server    │
                       │get_crypto_prices│
                       └────────┬────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │ CoinGeckoClient │
                       └────────┬────────┘
                                │
                                ▼
                          CoinGecko API
                                │
                                ▼
                          Market Data
                                │
                                ▼
                             Claude
                                │
                                ▼
                           Final Answer

---

4. Agentic Tool-Calling Flow

The project uses a two-turn Claude workflow.

Turn 1

User Request
 ↓
Claude
 ↓
Claude determines live data is required
 ↓
Claude returns tool_use

Example:

{
  "name": "get_crypto_prices",
  "input": {
    "coin_ids": ["bitcoin", "ethereum"],
    "currency": "usd"
  }
}

Tool Execution

Claude
 ↓
LiveOpsAgent
 ↓
McpClientAdapter
 ↓
MCP Server
 ↓
CoinGecko

Turn 2

MCP Result
 ↓
LiveOpsAgent
 ↓
Claude
 ↓
Final Answer

This demonstrates genuine agentic tool use rather than manually inserting an API response into a prompt.

---

5. MCP Tool

Current primary MCP tool:

get_crypto_prices

Description:

Get live cryptocurrency prices from CoinGecko.

Input:

{
  "coin_ids": ["bitcoin", "ethereum"],
  "currency": "usd"
}

Conceptual schema:

{
  "type": "object",
  "properties": {
    "coin_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "currency": {
      "type": "string",
      "default": "usd"
    }
  },
  "required": ["coin_ids"]
}

The MCP client discovers the tool and its schema dynamically.

---

6. Core Components

LiveOpsAgent

Location:

src/mcp_liveops/core/agent.py

Responsibilities:

1. Discover MCP tools.
2. Convert MCP tools into Claude tool definitions.
3. Send the initial Claude request.
4. Detect tool calls.
5. Invoke MCP tools.
6. Normalize tool results.
7. Build the second Claude request.
8. Return the final response.

McpClientAdapter

Provides the application-facing MCP boundary.

Responsibilities:

• Tool discovery
• Tool definition normalization
• Tool invocation
• Result normalization
• Error normalization
• Text extraction

McpCoinGeckoTools

Exposes CoinGecko functionality through MCP.

CoinGeckoClient

Owns the external CoinGecko API interaction.

AnthropicClaudeClient

Owns the Anthropic API integration behind the ClaudeClient abstraction.

---

7. Project Structure

mcp-liveops/
│
├── .github/
│   └── workflows/
│
├── docs/
│
├── src/
│   └── mcp_liveops/
│       ├── acquisition/
│       │   ├── api_models.py
│       │   ├── api_normalization.py
│       │   ├── external_api.py
│       │   ├── interface.py
│       │   ├── local_text.py
│       │   ├── models.py
│       │   ├── normalization.py
│       │   ├── web.py
│       │   └── web_models.py
│       │
│       ├── config/
│       │   └── settings.py
│       │
│       ├── core/
│       │   ├── agent.py
│       │   └── health.py
│       │
│       ├── evidence/
│       │   ├── memory.py
│       │   ├── models.py
│       │   ├── repository.py
│       │   ├── validation.py
│       │   └── validator.py
│       │
│       ├── mcp/
│       │   ├── client.py
│       │   ├── coingecko_tools.py
│       │   ├── integration_server.py
│       │   ├── models.py
│       │   ├── registry.py
│       │   └── server.py
│       │
│       └── providers/
│           └── claude/
│               ├── client.py
│               └── models.py
│
├── tests/
│   └── unit/
│
├── .env.example
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── README.md
├── sonar-project.properties
└── uv.lock

Project 9 was used as the verified baseline where appropriate. Proven infrastructure was reused instead of rebuilt unnecessarily.

---

8. Technology Stack

Technology Purpose

---

Python 3.12 Application language UV Environment/dependency management Claude / Anthropic LLM and tool-selection layer MCP Tool interoperability CoinGecko Real-time market data Pydantic Validation/domain models Pytest Automated testing Ruff Linting Git Version control GitHub Repository hosting Docker Containerization foundation GitHub Actions CI foundation

---

9. Environment

Python requirement:

Python >= 3.12,<3.13

Verified development version:

Python 3.12.10

---

10. Installation

Clone the repository:

git clone https://github.com/Mayank1532/mcp-liveops-.git
cd mcp-liveops-

Synchronize the environment:

uv sync

Verify Python:

uv run python --version

---

11. Configuration

Create the local environment file:

Copy-Item .env.example .env

Configure:

ANTHROPIC_API_KEY=your_api_key_here

Never commit .env or real credentials.

Use .env.example for safe placeholder configuration.

---

12. CoinGecko Data Model

Normalized market data contains:

coin_id
currency
price
change_24h_percent
last_updated_at

Example:

{
  "coin_id": "bitcoin",
  "currency": "usd",
  "price": 63534.0,
  "change_24h_percent": 0.82,
  "last_updated_at": 1786944230
}

Live values change continuously and therefore are not hard-coded.

---

13. Dependency Injection

The project uses dependency injection for provider boundaries.

Example:

McpCoinGeckoTools(
    client=fake_client
)

and:

LiveOpsAgent(
    claude_client=fake_claude
)

Benefits:

• Deterministic testing
• Provider isolation
• Easier maintenance
• Easier provider replacement

---

14. Error Handling

Important failure cases include:

Failure Expected behavior

---

Empty cryptocurrency list Tool validation failure Unknown MCP tool Normalized MCP failure CoinGecko unavailable Provider/API failure Invalid API response Validation/normalization failure Missing Anthropic key Configuration error MCP tool failure Failure propagated to agent No Claude tool call Direct Claude response Claude requests a tool MCP tool executed

The application does not silently turn external failures into successful empty responses.

---

15. Why MCP?

A direct implementation could be:

Claude
 ↓
Application API code
 ↓
CoinGecko

MCP provides:

Claude
 ↓
MCP Tool
 ↓
Provider

Benefits:

• Standardized tool interfaces
• Tool discovery
• Explicit schemas
• Clear boundaries
• Interoperability
• Easier future tool additions
• Separation between model reasoning and external capabilities

---

16. Why a Claude Abstraction?

The application depends on:

ClaudeClient

rather than directly depending on the Anthropic implementation.

This allows:

• Deterministic fake clients
• Fast unit tests
• Provider replacement
• Cleaner architecture
• Reduced coupling

---

17. Testing Strategy

Testing is proportional to the project scope.

Coverage includes:

• Unit tests
• MCP tests
• CoinGecko tests
• Claude gateway tests
• Agent orchestration tests
• Failure tests
• Live API validation
• End-to-end validation

Full Suite

uv run pytest -q

Verified:

105 passed

Ruff

uv run ruff check src tests

Verified:

All checks passed!

Agent Tests

uv run pytest tests\unit\test_agent.py -q

Verified:

3 passed

MCP CoinGecko Tests

uv run pytest tests\unit\test_mcp_coingecko_tools.py -q

Verified:

4 passed

Claude Gateway Tests

uv run pytest tests\unit\test_claude_gateway.py -q

Verified:

7 passed

---

18. Live API Validation

The CoinGecko integration was successfully validated against the real API.

The validated path was:

MCP
 ↓
get_crypto_prices
 ↓
CoinGecko
 ↓
Bitcoin + Ethereum
 ↓
Structured MCP Result

Real live values were retrieved successfully.

---

19. End-to-End Validation

The complete vertical slice was validated using:

• Deterministic Claude behavior
• Real MCP server
• Real CoinGecko API
• Agent orchestration

Validated flow:

MCP tool discovery
        ↓
Claude tool definition
        ↓
Claude tool call
        ↓
MCP invocation
        ↓
Real CoinGecko API
        ↓
Structured result
        ↓
Tool result returned to Claude
        ↓
Final Claude response

Validation result:

VALIDATION RESULT: PASS

---

20. Bruno

Bruno is part of the final API-validation gate.

Expected coverage:

• Successful API request
• Expected response structure
• Valid cryptocurrency identifiers
• Invalid input
• Relevant API failure behavior

Bruno should complement, not duplicate, the Pytest suite.

Final project completion requires the Bruno validation gate to pass.

---

21. DevOps

The project retains the verified baseline infrastructure where appropriate:

UV
Git
GitHub
Docker
GitHub Actions
Ruff
Mypy configuration
SonarQube configuration

The project intentionally avoids unnecessary cloud/platform complexity.

---

22. Docker

Build the image:

docker build -t mcp-liveops .

Docker provides a reproducible execution environment.

Docker is supporting infrastructure rather than the main learning objective.

---

23. Security

Security principles:

• Keep API keys in environment variables.
• Never commit .env.
• Use .env.example for placeholders.
• Validate external input.
• Normalize external API responses.
• Propagate failures explicitly.
• Keep provider credentials outside source code.

---

24. Cost

Most automated development testing is inexpensive because Claude is mocked during unit tests.

No database, GPU, vector database, or cloud infrastructure is required for the core workflow.

Real Claude API requests may incur usage costs.

The intended pattern is:

Unit Tests
 ↓
Fake Claude

and:

Final Validation
 ↓
Real Claude Credentials

---

25. Performance

The main latency contributors are:

Claude request
+
MCP execution
+
CoinGecko network request
+
Claude second request

The two-turn agentic flow naturally introduces more latency than a single LLM request.

Possible production improvements:

• Caching
• Connection pooling
• Timeouts
• Bounded retries
• Rate-limit handling
• Streaming
• Metrics
• Tracing
• Observability

These are outside the current mini-project scope.

---

26. Limitations

Current limitations:

• One primary external API
• One primary MCP tool
• Limited agent loop
• No persistent memory
• No multi-agent architecture
• No RAG
• No vector database
• External API dependency
• Claude dependency
• No production cloud deployment

These limitations are intentional to prevent scope creep.

---

27. Design Decisions

One External API

CoinGecko is sufficient to demonstrate live API + MCP integration.

One Primary MCP Tool

get_crypto_prices is sufficient to demonstrate discovery, schema, invocation, and result handling.

Provider Boundary

CoinGecko HTTP logic remains separate from MCP orchestration.

Claude Abstraction

The application depends on ClaudeClient, enabling deterministic tests.

Two-Turn Agentic Loop

The workflow is:

Claude → Tool
Tool → Claude

This demonstrates actual agentic tool use.

Deterministic Tests

Mocks and fakes are preferred during development. Real credentials and external services are reserved for final validation.

---

28. Interview Questions and Answers

Q1. What is MCP?

MCP stands for Model Context Protocol. It provides a standardized way for AI applications to interact with external tools and capabilities.

Q2. Why use MCP instead of directly calling CoinGecko?

MCP provides a standardized tool boundary. Claude does not need to know the implementation details of the external API.

Q3. How does Claude decide to use the tool?

Claude receives the available tool definitions and their schemas. Based on the user's request, it can produce a tool_use request.

Q4. What is tool discovery?

Tool discovery means asking the MCP server which tools it exposes and obtaining their names, descriptions, and input schemas.

Q5. Why use dependency injection?

It allows real providers to be replaced with deterministic test doubles, improving testability and reducing external dependencies during testing.

Q6. Why are most Claude tests mocked?

Real model calls can be slower, expensive, nondeterministic, and credential-dependent. Unit tests should be fast and repeatable.

Q7. Why are there two Claude calls?

The first call decides whether a tool is needed. The second call receives the tool result and produces the final answer.

Q8. What happens if CoinGecko fails?

The provider failure is propagated through the MCP layer and normalized by the client so the agent can handle the failure.

Q9. What happens if Claude requests an unknown tool?

The MCP client returns a normalized unsuccessful result rather than silently executing an unavailable capability.

Q10. How would you scale this system?

Potential production improvements include caching, retries, rate-limit handling, observability, authentication, authorization, multiple MCP servers, tool governance, and persistent state.

---

29. Lessons Learned

MCP is a tool interoperability layer

It separates AI reasoning from external capabilities.

Tool schemas matter

Claude needs a clear description of what the tool does and which arguments it accepts.

Agentic workflows are loops

LLM
 ↓
Tool Request
 ↓
Tool Execution
 ↓
Tool Result
 ↓
LLM

Provider boundaries improve testing

Claude and CoinGecko can be replaced with deterministic fakes.

Live validation matters

Mocks verify application behavior; live validation verifies the actual external integration.

---

30. Project 9 Reuse

Project 9 was used as the verified baseline where appropriate.

Reused patterns include:

• UV
• Configuration
• Environment management
• Pydantic
• Acquisition boundaries
• MCP integration
• Claude provider abstraction
• Testing patterns
• Docker
• CI foundation
• Linting
• Documentation patterns

Project 10 adds the new focus:

MCP
+
Claude
+
Live API
+
Agentic Tool Use

---

31. Why the Project Is Small

The objective is not to build a full AI platform.

The objective is to prove one technically meaningful vertical slice:

Claude
+
MCP
+
Live API
+
Agentic Tool Calling
+
Testing
+
Industry Engineering

Once the required capability works and is validated, unrelated functionality becomes scope creep.

---

32. Future Improvements

Potential future work, outside current Project 10 scope:

• Additional MCP tools
• Multiple market-data providers
• Currency conversion
• Market-news tool
• Caching
• Retry policies
• Rate-limit management
• Persistent conversation state
• Streaming
• Rich observability
• Authentication
• Authorization
• Cloud deployment
• MCP server hosting
• Production monitoring

---

33. Final Architecture Summary

                    USER
                      │
                      ▼
                 ┌─────────┐
                 │ Claude  │
                 └────┬────┘
                      │
                   tool_use
                      │
                      ▼
              ┌───────────────┐
              │ LiveOpsAgent  │
              └───────┬───────┘
                      │
                      ▼
             ┌─────────────────┐
             │ McpClientAdapter│
             └────────┬────────┘
                      │
                      ▼
             ┌─────────────────┐
             │   MCP Server    │
             │                 │
             │get_crypto_prices│
             └────────┬────────┘
                      │
                      ▼
             ┌─────────────────┐
             │ CoinGeckoClient │
             └────────┬────────┘
                      │
                      ▼
                CoinGecko API
                      │
                      ▼
                  Market Data
                      │
                      ▼
                   Claude #2
                      │
                      ▼
                 FINAL ANSWER

---

34. Release Checklist

[✓] Project objective implemented
[✓] Real CoinGecko API validated
[✓] MCP server validated
[✓] MCP tool validated
[✓] MCP tool discovery validated
[✓] MCP schema exposed
[✓] Claude tool definition generated
[✓] Claude tool call handled
[✓] MCP tool invocation works
[✓] Tool result returned to Claude
[✓] Two-turn agentic loop works
[✓] MCP failure handling validated
[✓] Invalid input handling validated
[✓] Pytest passes
[✓] Ruff passes
[✓] End-to-end deterministic validation passes
[✓] Real CoinGecko validation passes
[ ] Bruno validation completed
[ ] Final DevOps validation completed
[ ] Final repository cleanliness verified

Unchecked items must not be marked complete until actually validated.

---

35. Current Project Status

Core agentic vertical slice: COMPLETE

Verified:

105 automated tests passing
Ruff checks passing
Real CoinGecko API working
MCP tool discovery working
MCP tool invocation working
Claude tool-call orchestration working
Two-turn Claude/MCP loop working
End-to-end deterministic validation passing

Final release remains gated by the remaining Bruno, DevOps, and repository-cleanliness checks.

---

36. Final Takeaway

MCP-LIVEOPS demonstrates a complete agentic tool-use architecture using a real external API:

User Request
     ↓
Claude Reasoning
     ↓
MCP Tool Selection
     ↓
MCP Invocation
     ↓
Real CoinGecko API
     ↓
Structured Result
     ↓
Claude
     ↓
Grounded Final Answer

The project combines:

Claude
+
MCP
+
Live API
+
Agentic AI
+
Structured Tool Schemas
+
Error Handling
+
Testing
+
DevOps

while keeping the implementation small enough to understand, test, demonstrate, and explain.