Copilot MCP

MCP server exposing 14 real-time financial data tools to Microsoft Copilot Studio, deployed on Google Cloud Run and connected to a Copilot agent powered by GPT-4.1, published to Microsoft Teams.

🎯 TL;DR

This project demonstrates MCP (Model Context Protocol) as a standard way to connect AI agents to real-time financial data:

• 14 financial tools covering stock prices, earnings, analyst recommendations, insider activity, SEC filings, forex, and crypto.
• Finnhub API as the data source (free tier — swap base URL and token for any financial API in production).
• Google Cloud Run for hosting — stable public HTTPS URL, scales to zero when idle.
• Microsoft Copilot Studio as the agent layer — connects via the native MCP connector, no custom Microsoft-side code required.
• Microsoft Teams as the end-user surface — users query live market data through natural language conversation.

💡 Problem / Motivation

The Integration Challenge

Connecting an AI agent to real-time external data has historically required significant custom engineering. Every integration is one-off — custom APIs, custom parsers, custom connectors. For a financial data provider, this means every client who wants to build an AI workflow on top of their data has to figure out the integration themselves.

There is also no standard for how agents discover what a server can do, what inputs it expects, or how to call it. This creates friction at every layer: the data provider, the platform team, and the end-user application.

The Solution

MCP (Model Context Protocol) changes this by providing a standard interface for agents to discover and call external tools. Microsoft Copilot Studio now supports it natively. This means:

• ✅ One server wraps the financial API and exposes tools in a standard format.
• ✅ Any MCP-compatible agent can connect to it immediately, no custom integration work required.
• ✅ Copilot Studio discovers all tools automatically via the initialize handshake, no manual registration.
• ✅ Natural language queries in Teams or Microsoft 365 translate directly into live API calls.
• ✅ Stateless design maps perfectly to a serverless container — each request is fully independent.

📊 Financial Tools

14 tools covering the main areas of financial data analysis:

Tool	Category	Description
get_stock_quote	Price	Real-time stock price, open/high/low/close, and % change
get_company_profile	Company	Name, exchange, sector, market cap, country, and logo URL
search_symbol	Company	Find a ticker symbol by searching a company name or keyword
get_financials	Financials	Key metrics: P/E, EPS, beta, 52-week range, ROE, margins
get_earnings_calendar	Earnings	Upcoming and past earnings dates with estimates vs actuals
get_earnings_surprises	Earnings	Historical EPS beat/miss history by quarter
get_recommendations	Analyst	Analyst buy/hold/sell counts per reporting period
get_company_news	News	Latest news headlines for a specific company (last 30 days)
get_market_news	News	General market news by category (general, forex, crypto, merger)
get_sec_filings	Filings	SEC filings list: 10-K, 10-Q, 8-K with links
get_insider_transactions	Insider	Insider buy and sell transactions with shares and value
get_ipo_calendar	Events	Upcoming and past IPO listings with pricing details
get_forex_symbols	Markets	Available forex trading pairs by exchange
get_crypto_symbols	Markets	Available crypto trading pairs by exchange (default: Binance)

All tool inputs are validated with Zod before hitting the API.

Tool Design Decisions

The consumer of this data is an AI agent, not a developer — focused and predictable responses produce better results than large, unfiltered ones:

Tool	Decision
get_financials	Filters Finnhub's 100+ metric fields down to 20 key ones
get_earnings_calendar	Defaults to today through 90 days ahead when no dates are provided
get_company_news	Always fetches the last 30 days, caps at 5 articles (max 50)
get_sec_filings	Returns the 10 most recent filings
get_forex_symbols / get_crypto_symbols	Capped at 50 pairs per response

📁 Project Structure

Copilot-MCP/
│
├── server.js                          # MCP server — all 14 tools defined here
├── Dockerfile                         # Container definition for Cloud Run
├── .dockerignore
├── package.json
│
├── tests/
│   ├── mcp/
│   │   └── mcp_test_tools.js         # Calls every tool against the deployed server
│   ├── api/
│   │   ├── api_test_free_endpoints.py
│   │   └── api_list_free_endpoints.txt
│   └── copilot/
│       └── copilot_test_prompts.txt  # Sample prompts for manual Copilot testing
│
└── images/                            # Screenshots used in this README

Key Dependencies

"@modelcontextprotocol/sdk": "^1.28.0",
"express": "^5.2.1",
"zod": "^4.3.6",
"dotenv": "^17.3.1"

🔬 Architecture

Request Flow

When a user sends a message in Teams, the request travels through several layers before an answer comes back:

User (Teams)
    │  natural language question
    ▼
Microsoft Copilot Studio (GPT-4.1)
    │  selects the right tool and arguments
    │  POST /mcp  (MCP JSON-RPC format)
    ▼
Google Cloud Run  (this server)
    │  createServer() — fresh instance per request
    │  Zod validates the tool arguments
    │  tool handler fires
    ▼
Finnhub REST API
    │  GET /endpoint?symbol=AAPL&token=...
    ▼
JSON → wrapped in MCP format → agent → formatted answer → Teams

The entire round trip typically takes 3 to 5 seconds. Copilot Studio maintains the conversation history throughout a session — the server is stateless by design.

Tool Handler Flow

Each tool call follows this internal path:

Server Design

• Stateless: A fresh McpServer instance is created on every incoming request via createServer(). No shared state between requests — the conversation context lives in Copilot Studio.
• Streamable HTTP: Each tool call is its own independent HTTP POST. No persistent connections between calls — the right transport for quick, self-contained data fetches.
• Input validation: Every tool uses a Zod schema to validate arguments before the handler runs. Malformed inputs are rejected before they reach the API.
• Cloud native: Deployed on Google Cloud Run — scales to zero when idle, scales up automatically under load, stable public HTTPS URL with no manual certificate management.

📈 Agent in Action

The agent running live in Microsoft Teams, answering natural language questions about stocks and companies:

Inside Copilot Studio's test panel, you can watch the agent select tools and inspect the raw tool input and output before it gets formatted into a response:

🚀 Getting Started

Installation

git clone https://github.com/pedroalexleite/Copilot-MCP.git
cd Copilot-MCP
npm install

Create a .env file:

FINNHUB_API_KEY=your_key_here

Start the server locally:

node server.js
# → MCP server running on http://localhost:3000

Deploy to Google Cloud Run

Requires the gcloud CLI and a GCP project with billing enabled.

gcloud services enable run.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com

gcloud run deploy copilot-mcp \
  --source . \
  --region europe-southwest1 \
  --allow-unauthenticated \
  --set-env-vars FINNHUB_API_KEY=your_key_here \
  --port 8080

--source . uploads the source code, builds the Docker image via Cloud Build, stores it in Artifact Registry, and deploys it as a live service — no manual Docker registry management. At the end of the command you get a public HTTPS URL. To redeploy after changes, run the same command — Cloud Run does a zero-downtime rolling update.

Cold starts: Cloud Run scales to zero when idle. Run gcloud run services update copilot-mcp --min-instances 1 before a live demo to keep one instance always warm.

Connect to Microsoft Copilot Studio

1. Create the agent

Go to Microsoft Copilot Studio → Create → give the agent a name and select the language.

2. Select the model

For tool calling and data retrieval, GPT-4.1 handles tool selection reliably and efficiently. Copilot Studio also exposes GPT-5 and Claude variants depending on tenant configuration.

3. Write the agent instructions

The instructions are the system prompt — they tell the agent what it is, what data it has access to, and how to behave. Paste the following into the Instructions field:

You are a financial data assistant with access to real-time market data via the Finnhub API.
When a user asks about a company or stock, always start by searching for the ticker symbol if
it is not provided. Use the available tools based on what the user is asking about: stock prices
and market data, company background and sector information, financial ratios and metrics like
P/E, EPS, margins, beta and ROE, upcoming or past earnings dates and estimates, earnings
surprises and beat/miss history, analyst buy/hold/sell recommendations, company-specific or
broad market news, SEC filings such as 10-K, 10-Q and 8-K, insider buying and selling
activity, IPO listings, and forex or crypto trading pairs. Always present data in a clear,
concise format and explain financial metrics in plain language when relevant. If a tool returns
no data, say so clearly and suggest an alternative query.

4. Add the MCP server

Go to Tools → Add a tool → Model Context Protocol. Fill in the server name, a description, and the Cloud Run /mcp endpoint URL. Set Authentication to None.

Copilot Studio performs the initialize handshake automatically and discovers all 14 tools. Enable each tool you want the agent to call:

5. Publish the agent

Once tested, click Publish and choose your target channel. The agent was published to Microsoft Teams for this integration, but Copilot Studio also supports Microsoft 365, SharePoint, WhatsApp, Slack, Telegram, Facebook, Twilio, Dynamics 365, Salesforce, and ServiceNow.

Licensing: publishing to Teams requires a Teams license per end user, a tenant-level Copilot Studio license, and a Copilot Studio User License per publisher. Building and testing works on a trial, but publishing is locked until the user license is active.

Testing

Run every tool against the deployed server and report pass/fail:

node tests/mcp/mcp_test_tools.js

To test against a local server:

MCP_URL=http://localhost:3000/mcp node tests/mcp/mcp_test_tools.js

For interactive testing during development, run the MCP Inspector locally:

node server.js  # terminal 1
npx @modelcontextprotocol/inspector http://localhost:3000/mcp  # terminal 2

Select Streamable HTTP, set the URL to http://localhost:3000/mcp, Connection Type to Direct, and click Connect. The Inspector performs the same handshake Copilot Studio does — you can list tools, fill in arguments, run them, and inspect the raw response.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/NewFeature).
3. Commit your changes (git commit -m 'Add new feature').
4. Push to the branch (git push origin feature/NewFeature).
5. Open a Pull Request.