MCP | User Guide

MCP

April 11, 2026

MCP (Model Context Protocol) server for the 1up knowledge management platform. Enables AI coding assistants to interact with your 1up workspace - manage questionnaires, Q&A libraries, knowledge bases, and more directly from the terminal.

Cloud-Hosted MCP Server

The 1up MCP server is hosted at mcp.1up.ai — no local installation required. Your MCP client connects over HTTPS using Streamable HTTP transport, and authentication is handled via OAuth (you'll be prompted to log in through your browser on first use).

Installation

With pip pip install 1up-mcp

# With pipx (isolated install, recommended for CLI tools)  pipx install 1up-mcp  
# With uvx (zero-install, runs directly)  uvx 1up-mcp auth login

Requires Python 3.10+

Authentication

1up-mcp auth login # Opens browser for SSO login
1up-mcp auth status # Show current auth status
1up-mcp auth logout # Remove cached credentials

Credentials are cached locally in ~/.1up/credentials.json and automatically refreshed.

Claude Code

Add to your .claude.json or ~/.claude.json:

{ "mcpServers": { "1up": { "type": "http", "url": "https://mcp.1up.ai/mcp", "clientId": "TAWQL8mbs0eHLzaBaxV3Va5vH6qal4Wq" } } }

Claude Desktop

Add to claude_desktop_config.json:

{ "mcpServers": { "1up": { "type": "http", "url": "https://mcp.1up.ai/mcp" } } }

Cursor / Windsurf

Add to your MCP configuration:

{ "mcpServers": { "1up": { "type": "http", "url": "https://mcp.1up.ai/mcp" } } }

Migrating from Local (PyPI) Install

If you previously installed 1up-mcp locally via pip, pipx, or uvx, follow these steps to switch to the cloud-hosted server.

1. Update your MCP client configuration

Replace your existing 1up MCP server entry with the hosted version. Your old config looks like one of these:

// Old — local stdio server (remove this)
{ "command": "1up-mcp" }
{ "command": "uvx", "args": ["1up-mcp"] }

Replace it with:

// New — cloud-hosted server
{ "type": "http", "url": "https://mcp.1up.ai/mcp" }

2. Uninstall the local package

If installed with pip pip uninstall 1up-mcp

# If installed with pipx  pipx uninstall 1up-mcp

3. Clean up local credentials (optional)

The hosted server handles authentication via OAuth in your browser — cached local credentials are no longer needed.

rm -rf ~/.1up

Environment Variables

These are optional — credentials from 1up-mcp auth login are used by default.
Variable Description
ONEUP_AUTH_TOKEN Bearer token (overrides cached credentials)
ONEUP_API_URL API base URL
ONEUP_WORKSPACE_ID Workspace ID to use

Available Tools

Q&A Library (6 tools)
Tool Description
ask_question Query the knowledge base with optional filters
search_qa_library Search Q&A pairs with pagination
get_qa_pair Get a specific Q&A pair by ID
create_qa_pair Create a new Q&A pair
update_qa_pair Update an existing Q&A pair
delete_qa_pair Archive a Q&A pair

Questionnaires (11 tools)
Tool Description
upload_questionnaire Upload XLSX/DOCX/PDF/CSV questionnaire files
list_questionnaires List questionnaires with status/search filters
get_questionnaire Get full questionnaire details
get_questionnaire_questions Get questions with answers
update_questionnaire_answer Edit a specific answer
approve_question Mark an answer as approved
bulk_approve_questions Approve multiple questions at once
regenerate_answer Regenerate AI answer for a question
assign_question Assign a question to a team member
add_question_comment Add a comment to a question
request_questionnaire_export Export as XLSX/DOCX/CSV

Knowledge Base (4 tools)
Tool Description
list_kb_items List items with search/source filters
get_kb_item Get KB item details
upload_kb_document Upload PDF/DOCX/XLSX/CSV documents
delete_kb_item Delete a KB item

Knowledge Groups (5 tools)
Tool Description
list_knowledge_groups List all groups
get_knowledge_group Get group with its documents and Q&A pairs
create_knowledge_group Create a new group
add_items_to_knowledge_group Add documents/Q&A pairs to a group
remove_items_from_knowledge_group Remove items from a group
delete_knowledge_group Delete a group (items are ungrouped, not deleted)

Workspace (4 tools)
Tool Description
list_workspaces List accessible workspaces
get_workspace_info Get workspace details, plan, limits, usage
switch_workspace Switch active workspace
get_audit_events Get audit events with pagination