Demo MCP Basic
This project demonstrates a fundamental client-server interaction using the Model Context Protocol (MCP). MCP allows AI models, like those accessed via the AI SDK (e.g., Google Gemini/Vertex AI), to securely discover and utilize external tools or resources provided by a separate server process.
In this example:
- The Server (
src/server/) acts as an MCP provider, offering simple calculation tools (addition, subtraction, etc.). - The Client (
src/client/) uses the AI SDK to interact with a Google AI model and connects to the MCP server to make the server's tools available to the AI during generation.
This setup illustrates how you can extend the capabilities of AI models by giving them access to custom functionalities hosted on an MCP server.
Prerequisites
- Node.js (Version >=23.0.0 as specified in
package.json) - npm (comes with Node.js)
- A Google AI (Gemini) API Key. You can obtain one from Google AI Studio. (Required for using Gemini models).
Setup
-
Clone the repository:
bash git clone git@github.com:bertrandgressier/demo-ts-mcp-client-server.git cd demo-mcp-basic -
Install dependencies:
bash npm install -
Create Environment File:
Copy the example environment file.env.exampleto a new file named.env:bash cp .env.example .envThen, edit the
.envfile to add your actual API keys and configuration. The required and optional variables are:```dotenvRequired for Google Studio Models (Gemini)
GOOGLE_API_KEY=YOUR_GOOGLE_API_KEY
Required for Google Vertex AI Models
VERTEX_PROJECT_ID=YOUR_VERTEX_PROJECT_ID
Optional: Defaults to 'us-central1' if not set
VERTEX_LOCATION=your-vertex-location
Optional: Path to Vertex AI service account key file. Defaults to 'vertex-key.json' in the root if not set.
VERTEX_KEY_FILE=path/to/your/vertex-key.json
```
Replace
YOUR_GOOGLE_API_KEYandYOUR_VERTEX_PROJECT_IDwith your actual credentials.
If you use a Vertex AI key file, ensure it's placed correctly (e.g., in the root asvertex-key.jsonor provide the correct path inVERTEX_KEY_FILE).- Important: The
.gitignorefile is configured to prevent.envandvertex-key.jsonfrom being committed to Git.
- Important: The
Available Scripts
- Build TypeScript:
bash npm run build
Compiles TypeScript code from src to JavaScript in dist.
- Start Production Server:
bash npm run start # or specifically npm run start:server
Builds the project (if not already built) and runs the compiled server from dist/server/server.js.
- Start Production Client:
bash npm run start:client
Runs the compiled client from dist/client/client.js.
- Run Server in Development Mode:
bash npm run dev:server
Runs the server directly using ts-node (or similar via --experimental-transform-types) without needing a separate build step.
- Run Server in Development Mode with Watch:
bash npm run dev:server:watch
Runs the server using nodemon, automatically restarting it when changes are detected in the src/server directory.
- Run Client in Development Mode:
bash npm run dev:client
Runs the client directly usingts-node(or similar).
Example Client (src/client/client.ts)
The primary example client script demonstrates the following:
- Connects to the MCP Server: Establishes a connection to the locally running MCP server (expected at
http://localhost:3001/sse). - Fetches Tools: Retrieves the list of tools made available by the connected server.
- Configures AI Model: Uses the AI SDK (
generateText) configured with a Google AI model (Gemini via API Key or Vertex AI, depending on environment variables set in.envand potentiallysrc/models/google-ai-provider.ts). - Executes Prompt: Sends a prompt (
6 + 12) along with a system message instructing the AI to use the fetched tools to solve the calculation. - Outputs Result: Prints the final text response generated by the AI model after potentially using the server-provided tools.
This client serves as a basic illustration of how an application can interact with an MCP server to leverage its tools within an AI generation flow.
Project Structure
src/: Contains the TypeScript source code.client/: Code for the MCP client application.server/: Code for the MCP server application.model.ts: Handles AI model initialization and environment variable loading.dist/: Contains the compiled JavaScript code (after runningnpm run build)..env: Stores environment variables (API keys, etc.) - Do not commit this file.package.json: Project metadata and dependencies.tsconfig.json: TypeScript compiler configuration.