latitude-mcp-server

Quick Navigation

** Get Started**
** Features**
** Tools**
** Resources**
** CLI**

---

latitude-mcp-server gives your AI assistant superpowers for managing prompts on Latitude.so. Instead of switching between your IDE, Latitude dashboard, and AI chat, your AI can now create projects, version prompts, push content from local files, and even run prompts directly.

How it works:

• You: "Push my local prompt file to Latitude draft"
• AI: Reads file, extracts prompt path from filename, pushes to your project
• You: "Now run it with these parameters"
• AI: Executes prompt, streams response, maintains conversation
• Result: Full prompt lifecycle without leaving your IDE

---

Why This Beats Manual Management

Managing prompts manually is a context-switching nightmare. This MCP server makes traditional workflows look ancient.

We're not just wrapping an API. We're enabling AI-native prompt development with file-based workflows, automatic path derivation, and streaming execution.

---

Get Started in 60 Seconds

1. Get Your API Key

1. Go to app.latitude.so/settings
2. Create or copy your API key
3. That's it one key, all features unlocked

2. Configure Your MCP Client

Client	Config Location	Docs
Claude Desktop	claude_desktop_config.json	Setup
Claude Code	~/.claude.json or CLI	Setup
Cursor	.cursor/mcp.json	Setup
Windsurf	MCP settings	Setup

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "latitude": {
      "command": "npx",
      "args": ["latitude-mcp-server"],
      "env": {
        "LATITUDE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code (CLI)

One command setup:

claude mcp add latitude npx \
  --scope user \
  --env LATITUDE_API_KEY=your-api-key-here \
  -- latitude-mcp-server

Or manually add to ~/.claude.json:

{
  "mcpServers": {
    "latitude": {
      "command": "npx",
      "args": ["latitude-mcp-server"],
      "env": {
        "LATITUDE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor/Windsurf

Add to .cursor/mcp.json or MCP settings:

{
  "mcpServers": {
    "latitude": {
      "command": "npx",
      "args": ["latitude-mcp-server"],
      "env": {
        "LATITUDE_API_KEY": "your-api-key-here"
      }
    }
  }
}

** Pro Tip:** The server outputs in TOON format by default a token-efficient notation that uses 30-60% fewer tokens than JSON, keeping your LLM context lean.

---

Feature Breakdown

Feature	What It Does	Why You Care
** Projects**list & create	Manage Latitude projects	Organize prompts by use case
** Versions**draft live	Git-like version control	Safe iteration without breaking prod
** Prompts**full CRUD	Create, read, update prompts	Complete prompt lifecycle
** File Push**local cloud	Push prompts from local files	IDE-native workflow
** Execution**run & chat	Execute prompts with params	Test directly from AI
** Logs**monitoring	View execution history	Debug and optimize
** Streaming**real-time	Stream AI responses	See results as they generate

---

Tool Reference

This server provides 16 MCP tools covering the complete Latitude API.

---

Project Tools

latitude_list_projects

List all projects in your Latitude workspace.

// No parameters required
{}

Returns: Array of projects with id, name, createdAt, updatedAt

---

latitude_create_project

Create a new project.

Parameter	Type	Required	Description
name	string	Yes	Project name

{
  "name": "My Awesome Prompts"
}

---

Version Tools

latitude_list_versions

List all versions (commits) for a project.

Parameter	Type	Required	Description
projectId	string	Yes	Project ID

{
  "projectId": "27756"
}

---

latitude_get_version

Get details for a specific version.

Parameter	Type	Required	Description
projectId	string	Yes	Project ID
versionUuid	string	Yes	Version UUID

---

latitude_create_version

Create a new draft version (branch).

Parameter	Type	Required	Description
projectId	string	Yes	Project ID
name	string	Yes	Version/commit name

{
  "projectId": "27756",
  "name": "feature-new-tone"
}

---

latitude_publish_version

Publish a draft version to make it live.

Parameter	Type	Required	Description
projectId	string	Yes	Project ID
versionUuid	string	Yes	Draft version UUID
title	string	No	Publication title
description	string	No	Publication notes

---

Prompt Tools

latitude_list_prompts

List all prompts in a version.

Parameter	Type	Required	Default	Description
projectId	string	Yes		Project ID
versionUuid	string	No	"live"	Version UUID

---

latitude_get_prompt

Get a specific prompt by path.

Parameter	Type	Required	Default	Description
projectId	string	Yes		Project ID
path	string	Yes		Prompt path (e.g., "my-prompt")
versionUuid	string	No	"live"	Version UUID

{
  "projectId": "27756",
  "path": "onboarding/welcome",
  "versionUuid": "79b52596-7941-4ed3-82cf-23e13fa170db"
}

---

latitude_push_prompt

Push prompt content to a draft version.

Parameter	Type	Required	Default	Description
projectId	string	Yes		Project ID
versionUuid	string	Yes		Draft version UUID
path	string	Yes		Prompt path
content	string	Yes		Full prompt content with frontmatter
force	boolean	No	false	Overwrite if exists

{
  "projectId": "27756",
  "versionUuid": "79b52596-7941-4ed3-82cf-23e13fa170db",
  "path": "greeting",
  "content": "---\nprovider: openai\nmodel: gpt-4o-mini\n---\nHello {{name}}! Welcome to our service."
}

---

latitude_push_prompt_from_file

Push a prompt directly from a local file. This is the killer feature for IDE workflows.

Parameter	Type	Required	Default	Description
projectId	string	Yes		Project ID
versionUuid	string	Yes		Draft version UUID
filePath	string	Yes		Absolute path to prompt file
promptPath	string	No	derived	Path in Latitude (auto-derived from filename)
force	boolean	No	false	Overwrite if exists

Auto-derivation: If you push /path/to/my-prompt.md, it automatically becomes my-prompt in Latitude.

{
  "projectId": "27756",
  "versionUuid": "79b52596-7941-4ed3-82cf-23e13fa170db",
  "filePath": "/Users/you/prompts/welcome-message.md"
}

Supported extensions: .md, .promptl, .txt

---

Execution Tools

latitude_run_prompt

Execute a prompt and get AI response.

Parameter	Type	Required	Default	Description
projectId	string	Yes		Project ID
path	string	Yes		Prompt path
versionUuid	string	No	"live"	Version UUID
parameters	object	No	{}	Template variables
userMessage	string	No		Additional user input
stream	boolean	No	false	Enable streaming

{
  "projectId": "27756",
  "path": "greeting",
  "parameters": { "name": "World" },
  "stream": true
}

---

latitude_chat

Continue an existing conversation.

Parameter	Type	Required	Default	Description
conversationUuid	string	Yes		Conversation UUID
message	string	Yes		User message
stream	boolean	No	false	Enable streaming

---

latitude_get_conversation

Get full conversation history.

Parameter	Type	Required	Description
conversationUuid	string	Yes	Conversation UUID

---

Operations Tools

latitude_list_logs

Get execution logs for a prompt.

Parameter	Type	Required	Default	Description
projectId	string	Yes		Project ID
documentUuid	string	No		Filter by prompt UUID
page	number	No	1	Page number
pageSize	number	No	25	Results per page

---

latitude_create_log

Create a log entry for external executions.

Parameter	Type	Required	Description
projectId	string	Yes	Project ID
documentPath	string	Yes	Prompt path
messages	array	Yes	Conversation messages

---

latitude_trigger_evaluation

Trigger an evaluation run for a prompt.

Parameter	Type	Required	Description
projectId	string	Yes	Project ID
evaluationUuid	string	Yes	Evaluation UUID

---

Resource Templates

Access Latitude data via MCP resources (read-only):

Resource URI	Description
latitude://projects	List all projects
latitude://projects/{projectId}/versions	List versions for project
latitude://projects/{projectId}/versions/{versionUuid}/prompts	List prompts in version
latitude://projects/{projectId}/versions/{versionUuid}/prompts/{path}	Get specific prompt

---

CLI Reference

The server also works as a standalone CLI tool:

# Set your API key
export LATITUDE_API_KEY="your-key"

# Or use inline
LATITUDE_API_KEY="your-key" latitude-mcp projects list

Commands

# Projects
latitude-mcp projects list
latitude-mcp projects create "My Project"

# Versions
latitude-mcp versions list <projectId>
latitude-mcp versions create <projectId> "Draft Name"

# Prompts
latitude-mcp prompts list <projectId> -v <versionUuid>
latitude-mcp prompts get <projectId> <path> -v <versionUuid>

# Push (inline content)
latitude-mcp push <projectId> <versionUuid> <promptPath> --content "---\nprovider: openai\n---\nHello!"

# Push (from file) 
latitude-mcp push <projectId> <versionUuid> --file /path/to/prompt.md

# Run
latitude-mcp run <projectId> <path> -v <versionUuid> -p '{"name": "World"}'

# Chat
latitude-mcp chat <conversationUuid> -m "Follow up question"

Options

Flag	Description
-v, --version-uuid	Version UUID (default: "live")
-p, --parameters	JSON parameters for run
-m, --message	Message for chat
-s, --stream	Enable streaming
-o, --output-format	"toon" or "json" (default: "toon")
--file	Path to prompt file
--content	Inline prompt content
--force	Force overwrite

---

Recommended Workflows

Local Development Flow

1. Write prompt in your IDE: /prompts/my-feature.md
2. AI: "Push this to my Latitude draft"
    latitude_push_prompt_from_file
3. AI: "Run it with test parameters"
    latitude_run_prompt
4. Iterate on content locally
5. AI: "Push the updated version"
6. AI: "Publish to live"
    latitude_publish_version

Prompt Audit Flow

1. AI: "List all my Latitude projects"
    latitude_list_projects
2. AI: "Show me all prompts in project 27756"
    latitude_list_prompts
3. AI: "Get the content of the onboarding prompt"
    latitude_get_prompt
4. AI: "Check the execution logs"
    latitude_list_logs

Conversation Testing Flow

1. AI: "Run the support-bot prompt"
    latitude_run_prompt (returns conversationUuid)
2. AI: "Continue with: What about refunds?"
    latitude_chat
3. AI: "Show the full conversation"
    latitude_get_conversation

---

Environment Variables

Variable	Required	Default	Description
LATITUDE_API_KEY	Yes		Your Latitude API key
LATITUDE_BASE_URL	No	https://gateway.latitude.so	API base URL

---

Common Issues & Quick Fixes

Problem	Solution
"LATITUDE_API_KEY is required"	Set the env variable in your MCP config or shell
"Head commit not found"	Project has no published version use a specific versionUuid instead of "live"
"Provider API Key not found"	Add your LLM provider key (OpenAI, Anthropic) in Latitude settings
Push fails with "version is merged"	Can only push to draft versions create a new draft first
File push path wrong	The tool auto-derives from filename; use promptPath param to override

---

Development

# Clone
git clone https://github.com/yigitkonur/latitude-mcp-server.git
cd latitude-mcp-server

# Install
npm install

# Build
npm run build

# Test
npm test

# Run locally
LATITUDE_API_KEY=your-key node dist/index.js projects list

---

Built with because managing prompts should be as easy as writing code.

ISC Yiit Konur