# Jana MCP Server User Manual
**Version:** 2.1
**Last Updated:** 2026-01-22
**Service Provider:** Jana Earth Data
---
## Overview
The Jana MCP Server provides AI assistants (Cursor, Claude Code, and Claude Desktop) with access to the Jana Environmental Data Platform. This includes air quality measurements, greenhouse gas emissions, and facility-level environmental data from authoritative sources including OpenAQ, Climate TRACE, and EDGAR.
The MCP server is **hosted by Jana Earth Data** — you do not need to install or deploy anything. Simply configure your MCP client with your credentials and connect.
---
## Table of Contents
1. [Quick Start](#quick-start)
2. [Getting Your Credentials](#getting-your-credentials)
3. [Connection Methods](#connection-methods)
4. [Connecting from Cursor](#connecting-from-cursor)
5. [Connecting from Claude Code](#connecting-from-claude-code)
6. [Connecting from Claude Desktop](#connecting-from-claude-desktop)
7. [Available Tools](#available-tools)
8. [Security Considerations](#security-considerations)
9. [Troubleshooting](#troubleshooting)
---
## Quick Start
### Step 1: Get Your Credentials
Contact Jana Earth Data or your organization's administrator to receive:
- Your **username** and **password**
- The **MCP server URL** (e.g., `https://mcp.janaearth.com`)
### Step 2: Obtain Your API Token
Use your credentials to get an authentication token:
```bash
curl -X POST https://api.janaearth.com/api/auth/login/ \
-H "Content-Type: application/json" \
-d '{"username": "your_username", "password": "your_password"}'
```
**Response:**
```json
{
"token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b",
"user": {
"id": 1,
"username": "your_username",
"email": "you@company.com"
}
}
```
### Step 3: Configure Your MCP Client
**Simplest method** (works with all clients):
```json
{
"mcpServers": {
"jana": {
"url": "https://mcp.janaearth.com/sse?token=YOUR_TOKEN_HERE"
}
}
}
```
### Step 4: Start Using Jana
Restart your MCP client and try:
> "What's the air quality in London right now?"
---
## Getting Your Credentials
### For Enterprise Customers
Your organization's Jana Earth Data administrator will provision accounts for your team. Contact your admin or IT department for:
- Username and initial password
- MCP server URL for your organization
- Any usage policies or guidelines
### For Individual Users
1. Visit [Jana Earth Data Portal](https://portal.janaearth.com) (or contact sales@janaearth.com)
2. Complete the registration process
3. Receive your credentials via email
4. Change your password on first login
### Managing Your Token
Your API token does not expire automatically, but you can regenerate it at any time:
```bash
# Logout (invalidates current token)
curl -X POST https://api.janaearth.com/api/auth/logout/ \
-H "Authorization: Token YOUR_CURRENT_TOKEN"
# Login again to get a new token
curl -X POST https://api.janaearth.com/api/auth/login/ \
-H "Content-Type: application/json" \
-d '{"username": "your_username", "password": "your_password"}'
```
---
## Connection Methods
There are two ways to authenticate with the Jana MCP Server:
### Method 1: Token in URL (Simplest)
Include your token as a query parameter in the SSE URL:
```
https://mcp.janaearth.com/sse?token=YOUR_TOKEN
```
**Pros:** Works with all MCP clients, no extra software needed
**Cons:** Token visible in URL (mitigated by HTTPS encryption)
**This is the recommended method for most users.**
### Method 2: mcp-remote Proxy (More Secure)
Use the `mcp-remote` npm package to add authentication headers:
```json
{
"mcpServers": {
"jana": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.janaearth.com/sse",
"--header",
"Authorization:${JANA_TOKEN}"
],
"env": {
"JANA_TOKEN": "Token YOUR_TOKEN_HERE"
}
}
}
}
```
**Pros:** Token not visible in URL
**Cons:** Requires Node.js, adds complexity
**Use this if your security policy prohibits tokens in URLs.**
---
## Connecting from Cursor
### Option A: Direct URL (Recommended)
1. Open Cursor Settings (Cmd+, or Ctrl+,)
2. Search for "MCP" or navigate to Features → MCP Servers
3. Click "Add Server" and configure:
```json
{
"mcpServers": {
"jana": {
"url": "https://mcp.janaearth.com/sse?token=YOUR_TOKEN"
}
}
}
```
Or edit `~/.cursor/mcp.json` directly:
**macOS/Linux:**
```bash
nano ~/.cursor/mcp.json
```
**Windows:**
```
notepad %USERPROFILE%\.cursor\mcp.json
```
4. Restart Cursor or reload window (Cmd+Shift+P → "Developer: Reload Window")
### Option B: Using mcp-remote
Requires Node.js installed.
```json
{
"mcpServers": {
"jana": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.janaearth.com/sse",
"--header",
"Authorization:${JANA_TOKEN}"
],
"env": {
"JANA_TOKEN": "Token YOUR_TOKEN_HERE"
}
}
}
}
```
### Verify Connection
Test by asking your AI assistant:
> "Check the system health of the Jana platform"
---
## Connecting from Claude Code
Claude Code is Anthropic's agentic coding tool that runs in the terminal.
### Configuration
Edit `~/.claude/claude_code_config.json`:
**Option A: Direct URL**
```json
{
"mcpServers": {
"jana": {
"url": "https://mcp.janaearth.com/sse?token=YOUR_TOKEN"
}
}
}
```
**Option B: mcp-remote**
```json
{
"mcpServers": {
"jana": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.janaearth.com/sse",
"--header",
"Authorization:${JANA_TOKEN}"
],
"env": {
"JANA_TOKEN": "Token YOUR_TOKEN_HERE"
}
}
}
}
```
### Restart Claude Code
```bash
exit
claude
```
### Verify
```
> Check the system health of Jana
```
---
## Connecting from Claude Desktop
### Configuration
Edit the config file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**Option A: Direct URL**
```json
{
"mcpServers": {
"jana": {
"url": "https://mcp.janaearth.com/sse?token=YOUR_TOKEN"
}
}
}
```
**Option B: mcp-remote**
```json
{
"mcpServers": {
"jana": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.janaearth.com/sse",
"--header",
"Authorization:${JANA_TOKEN}"
],
"env": {
"JANA_TOKEN": "Token YOUR_TOKEN_HERE"
}
}
}
}
```
### Restart
Quit and restart Claude Desktop.
---
## Available Tools
Once connected, your AI assistant can use these tools:
| Tool | Description | Example Query |
|------|-------------|---------------|
| `get_air_quality` | Query air quality measurements (PM2.5, O3, NO2, etc.) | "What's the air quality in London?" |
| `get_emissions` | Query greenhouse gas emissions data | "Show CO2 emissions from power plants in Germany" |
| `find_nearby` | Find environmental monitoring stations near a location | "Find air quality stations within 50km of Paris" |
| `get_trends` | Analyze trends in environmental data over time | "Show PM2.5 trends in Beijing over the last year" |
| `get_data_summary` | Get an overview of available data | "What data is available in the platform?" |
| `get_system_health` | Check the platform's operational status | "Is the Jana platform healthy?" |
### Example Queries
**Air Quality:**
```
"What are the current PM2.5 levels in New York City?"
"Show me ozone measurements in California for the last week"
"Compare air quality between Tokyo and Seoul"
```
**Emissions:**
```
"What are the largest CO2 emitters in the steel sector in China?"
"Show methane emissions from oil and gas facilities in Texas"
"Get emissions data for power plants within 100km of Berlin"
```
**Geographic Search:**
```
"Find all environmental monitoring stations within 25km of the Eiffel Tower"
"What facilities are near coordinates -122.4, 37.8?"
```
---
## Security Considerations
### Token Security
| Method | Token Visibility | Security Level |
|--------|-----------------|----------------|
| URL query param | In URL (encrypted by HTTPS) | ⭐⭐⭐ Good |
| mcp-remote header | In local config file only | ⭐⭐⭐⭐ Better |
### Best Practices
**Protect Your Token:**
- Never share your token with others
- Don't commit config files with tokens to version control
- Regenerate your token if you suspect it's compromised
**Add to .gitignore:**
```gitignore
# MCP configuration with tokens
.cursor/mcp.json
claude_desktop_config.json
claude_code_config.json
```
**Secure Config Files (macOS/Linux):**
```bash
chmod 600 ~/.cursor/mcp.json
```
### Token Regeneration
If your token is compromised:
```bash
# 1. Logout (invalidates current token)
curl -X POST https://api.janaearth.com/api/auth/logout/ \
-H "Authorization: Token YOUR_COMPROMISED_TOKEN"
# 2. Get a new token
curl -X POST https://api.janaearth.com/api/auth/login/ \
-H "Content-Type: application/json" \
-d '{"username": "your_username", "password": "your_password"}'
# 3. Update your MCP configuration with the new token
```
### Rate Limits
| User Type | Rate Limit |
|-----------|------------|
| Standard | 1,000 requests/hour |
| Enterprise | Custom (contact sales) |
---
## Troubleshooting
### Connection Issues
**"Cannot connect to MCP server"**
1. Verify your internet connection
2. Check the URL is correct: `https://mcp.janaearth.com/sse?token=...`
3. Test the server: `curl https://mcp.janaearth.com/health`
**"MCP error -32602: Invalid request parameters"**
1. Reload your Cursor/Claude window
2. Restart the application
3. Check JSON syntax in your config file
### Authentication Errors
**"Authentication failed" or "Invalid token"**
1. Verify your token is correct (no extra spaces)
2. Get a fresh token by logging in again
3. Check that your account is active
**"Permission denied"**
Contact your administrator or Jana Earth Data support.
### Timeout Errors
**"Request timeout" or slow responses**
1. Try more specific queries (smaller geographic area, shorter date range)
2. Check backend health: ask "Is the Jana platform healthy?"
### mcp-remote Issues
**"npx: command not found"**
Install Node.js from https://nodejs.org/
**"mcp-remote: not found"**
Run manually first to install: `npx mcp-remote --version`
### Known Limitations
**`get_data_summary` returns partial results**
The data summary may return basic source information instead of full statistics due to backend query timeouts on large datasets.
---
## Getting Help
1. **Check status:** Ask "Is the Jana platform healthy?"
2. **Documentation:** [docs.janaearth.com](https://docs.janaearth.com)
3. **Support:** support@janaearth.com
4. **Enterprise:** Contact your account manager
---
## Architecture Overview
```
┌─────────────────────────────────────────────────────────────────┐
│ Your Machine │
│ │
│ ┌──────────────┐ │
│ │ Cursor/Claude│ │
│ │ (MCP Client) │ │
│ └──────┬───────┘ │
│ │ │
│ │ https://mcp.janaearth.com/sse?token=xxx │
└─────────┼────────────────────────────────────────────────────────┘
│
▼ (HTTPS - token encrypted in transit)
┌─────────────────────────────────────────────────────────────────┐
│ Jana Earth Data Cloud │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Jana MCP Server │────▶│ Jana Backend │ │
│ │ (validates │ │ (Environmental │ │
│ │ your token) │ │ Data API) │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │
│ ┌───────┴───────┐ │
│ │ Data Sources │ │
│ │ • OpenAQ │ │
│ │ • Climate TRACE│ │
│ │ • EDGAR │ │
│ └───────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
---
## Changelog
| Version | Date | Changes |
|---------|------|---------|
| 2.1 | 2026-01-22 | Corrected auth to use URL query param (works with all clients) |
| 2.0 | 2026-01-22 | Rewritten for hosted service with per-user auth |
| 1.0 | 2026-01-22 | Initial release |
