StartupFundingAgent - Production-Grade MCP

From Zero to Funding Pitch in 60 Seconds

StartupFundingAgent (also known as Grant Hunter MCP) is an enterprise-ready Model Context Protocol (MCP) server designed to autonomously hunt for non-dilutive funding, generate winning pitches using advanced AI frameworks, and seamlessly integrate with Google Workspace for execution.

---

📖 Table of Contents

• Core Features
• Architecture
• Security & Resilience
• Technical Stack
• Setup Instructions
• API Reference
• Environment Variables
• Project Structure
• MCP Integration
• Development
• Contributing
• Future Roadmap

---

🚀 Core Features

This MCP exposes three powerful, production-hardened endpoints:

1. /query_grants - Intelligent Grant Discovery

• Real-Time Search: Direct integration with Grants.gov API.
• Smart Filtering: Deduplicates and sorts opportunities by deadline.
• Keyword-Based Discovery: Search funding opportunities with flexible keyword matching.
• Resilient: Implements a 5x Retry Policy with Exponential Backoff to handle government API instability.

2. /generate_pitch - AI-Powered Pitch Architect

• Gemini Integration: Leverages Google's Gemini 2.0 Flash for high-speed, high-quality generation.
• 150-Word Precision: Generates compelling, concise funding pitches optimized for grant applications.
• Triple-Horizon Framework: Enforces a strict prompt structure (Acute Pain Point, Technical Deviation, Macro-Economic Lock) to maximize scoring potential.
• Graceful Fallback: Automatic template fallback ensures business continuity even if AI services are disrupted.

3. /manage_google_services - Secure Execution

• Gmail Integration: Auto-drafts personalized emails to grant officers.
• Calendar Sync: Automatically adds hard deadlines to your Google Calendar.
• Least Privilege: Operates with ephemeral OAuth tokens passed securely at runtime.

---

🏗️ Architectural Excellence

We have evolved the legacy Flask MVP into a Containerized FastAPI MCP Server, representing a paradigm shift in reliability and scalability.

• Microservices-Ready: Stateless architecture designed for orchestration.
• Type-Safe: Fully typed Python codebase for maintainability.
• Dockerized: "Write Once, Run Anywhere" deployment.

---

🛡️ Security & Resilience Pillars

We treat security and reliability as first-class citizens, not afterthoughts.

1. Lethal Trifecta Mitigation (Security)

• Zero Hardcoded Secrets: All API keys and Client IDs are sourced strictly from os.environ.
• Ephemeral Tokens: OAuth tokens are consumed via request body and never stored persistently.
• Secure Configuration: Comprehensive .gitignore ensures no secrets are committed.

2. Network Resilience (Reliability)

• Production AgentOps Standard: We overrode the legacy MAX_RETRY_ATTEMPTS=2 policy.
• 5x Retry Loop: All external API calls (Grants.gov, Google Services) implement a robust 5-attempt retry mechanism with exponential backoff to survive transient network failures (5xx/429).

3. Input Validation (Safety)

• Strict Pydantic Schemas: Every endpoint is protected by rigorous data models (GrantsQueryInput, PitchGenerateInput, etc.).
• Injection Prevention: Validated inputs prevent XSS and injection attacks before they reach business logic.

4. Logging Hygiene

• No PII in Logs: Email bodies and pitch drafts are never logged.
• Configurable Log Level: Set LOG_LEVEL=INFO for production; DEBUG for development.

---

🛠️ Technical Stack

• Runtime: Python 3.11 (Slim Docker Image)
• Framework: FastAPI (High-performance Async I/O)
• Server: Uvicorn (Standard ASGI)
• AI: Google Generative AI (Gemini 2.0 Flash)
• Integration: Google API Client (Gmail, Calendar)
• Validation: Pydantic v2

---

⚡ Setup Instructions

Get the agent running in seconds.

Prerequisites

• Docker (recommended) OR Python 3.11+
• A Gemini API key (get one at Google AI Studio)
• (Optional) Google OAuth credentials for Google Services integration

1. Configure Environment

# Copy the example environment file
cp .env.example .env

# Edit .env with your API keys
nano .env

Required variables:

• GEMINI_API_KEY: Your Google Gemini API key

2. Build the Container

docker build -t grant-hunter-mcp .

3. Run the Agent

docker run -p 8080:8080 --env-file .env grant-hunter-mcp

4. Verify

Access the auto-generated OpenAPI documentation: http://localhost:8080/docs

Alternative: Run Without Docker

# Install dependencies
pip install -r requirements.txt

# Run with Uvicorn
uvicorn main:app --reload --host 0.0.0.0 --port 8000

The server will be available at http://localhost:8000.

---

📚 API Reference

Health Check

GET /health

Returns server health status.

---

POST /query_grants

Search for grant opportunities.

Request Body:

{
  "keyword": "clean energy",
  "max_results": 20,
  "focus_area": "renewable energy"
}

Response:

{
  "results": [
    {
      "id": "DE-FOA-0003001",
      "title": "AI-Driven Clean Energy Optimization SBIR",
      "agency": "Department of Energy",
      "close_date": "December 15, 2025",
      "status": "Open",
      "data_status": "COMPLETE"
    }
  ],
  "total_count": 1,
  "execution_time_ms": 1250.5
}

---

POST /generate_pitch

Generate an AI-powered funding pitch.

Request Body:

{
  "startup_name": "CleanTech Solutions",
  "focus_area": "Renewable Energy",
  "grant_title": "Clean Energy Innovation Grant"
}

Response:

{
  "pitch_draft": "...",
  "model_used": "gemini-2.0-flash",
  "status": "SUCCESS"
}

---

POST /manage_google_services

Create Gmail draft and Calendar event for grant deadlines.

Request Body:

{
  "grant_title": "Clean Energy Innovation Grant",
  "deadline_date": "December 15, 2025",
  "oauth_token": "your_oauth_access_token"
}

Response:

{
  "gmail_status": "SUCCESS",
  "calendar_status": "SUCCESS",
  "draft_link": "https://mail.google.com/...",
  "event_link": "https://calendar.google.com/...",
  "errors": []
}

---

🔐 Environment Variables

Variable	Required	Description	Default
GEMINI_API_KEY	Yes	Google Gemini API key	-
GEMINI_MODEL	No	Gemini model to use	gemini-2.0-flash
LOG_LEVEL	No	Logging level	INFO
DEMO_MODE	No	Enable demo mode (skips real API calls)	FALSE

See .env.example for a complete list of available variables.

---

📁 Project Structure

mcp/
├── main.py                     # FastAPI application entry point
├── grants_gov_api.py           # Grants.gov API integration
├── pitch_generator.py          # AI pitch generation with Gemini
├── google_services_manager.py  # Gmail and Calendar integration
├── pydantic_models.py          # Input/output data models
├── mcp_definition.yaml         # MCP server definition
├── requirements.txt            # Python dependencies
├── .env.example                # Environment variables template
└── README.md                   # This file

---

🔌 MCP Integration

This server follows the Model Context Protocol specification. Use the mcp_definition.yaml file to configure your MCP client.

Using with Claude Desktop

1. Update mcp_definition.yaml with your server URL
2. Add the MCP server to your Claude Desktop configuration
3. Start using grant discovery and pitch generation in conversations

---

🧪 Development

Running Tests

[!WARNING] The tests directory is currently pending implementation. Please refer to TODO.md for the roadmap on adding unit and integration tests.

# Future command
# pytest tests/ -v

Linting

flake8 . --max-line-length=79
mypy . --strict

Security Notes

• Never commit .env files - Contains sensitive API keys
• OAuth tokens are ephemeral - Passed at runtime, never stored
• All inputs validated - Using Pydantic models with strict validation
• No hardcoded secrets - All credentials loaded from environment variables

---

🤝 Contributing

1. Check TODO.md for prioritized tasks
2. Follow the existing code style
3. Ensure all tests pass before submitting PRs
4. Never commit secrets or API keys

---

🔮 V2 Scope (Future Roadmap)

While this MVP delivers a complete "Grant Hunter" loop, our vision extends further:

• Advanced UI: React/Next.js dashboard for visual pipeline management.
• Team Collaboration: Multi-user support with role-based access control (RBAC).
• Analytics Engine: Dashboard for tracking win rates and funding funnel metrics.
• Full OAuth2 Flow: Implementing a dedicated auth service for token lifecycle management.
• Async Network Layer: Migration from requests to httpx planned for V2 to handle >10k concurrent connections (currently optimized for single-tenant stability).
• Brazil Adaptation: Support for Brazilian grant sources (Transferegov, etc.)

---

📄 License

MIT License - See LICENSE file for details.

---

Built with ❤️ for founders who are building the future.