MCP-Upstage-Server

You run a dedicated MCP server that connects to Upstage AI services to parse documents, extract structured information, generate schemas, and classify documents. It provides a robust, transport-flexible bridge between your client apps and Upstage’s capabilities, with built-in error handling, retries, and progress reporting.

How to use

You operate the MCP server from your command line or integrate it into your client workflow. Start it in stdio mode for simple, direct communication with a single client, or enable HTTP Streamable mode to support multiple clients over a network.

In stdio mode you launch the server with your API key set in the environment, and you communicate through standard input/output with your MCP client. In HTTP Streamable mode you expose a RESTful MCP endpoint over HTTP and listen on your chosen port.

How to install

Prerequisites you need before installation:

• Node.js 18.0.0 or higher

• An Upstage API key from Upstage Console

Install from npm

# Install globally
npm install -g mcp-upstage-server

# Or use with npx (no installation required)
npx mcp-upstage-server

Install from source

# Clone the repository
git clone https://github.com/UpstageAI/mcp-upstage.git
cd mcp-upstage/mcp-upstage-node

# Install dependencies
npm install

# Build the project
npm run build

# Set up environment variables
cp .env.example .env
# Edit .env and add your UPSTAGE_API_KEY

Running the server in stdio mode (default) requires your API key in the environment, then you start the server with npx

UPSTAGE_API_KEY=your-api-key npx mcp-upstage-server

Running the server with HTTP Streamable transport enables multiple clients and a RESTful interface. Start the server with the HTTP option

UPSTAGE_API_KEY=your-api-key npx mcp-upstage-server --http

If you want HTTP on a specific port

UPSTAGE_API_KEY=your-api-key npx mcp-upstage-server --http --port 8080

Configuration and usage notes

If you are integrating with Claude Desktop or another MCP client, you can configure a stdio-based server or an HTTP-based one. The stdio option uses a straightforward command invocation, while the HTTP option exposes a server endpoint you can connect to from your client.

Environment variable you must provide: UPSTAGE_API_KEY. Include it in the server process environment when starting the server. For example, in a deployment or integration script, set UPSTAGE_API_KEY to your actual API key or a secure secret mechanism.

Notes on transport options

stdio Transport (Default) Pros: Simple setup, direct process communication. Cons: Single client connection only.

HTTP Streamable Transport Pros: Multiple client support, network accessible, RESTful API. Cons: Requires port management and network configuration. Endpoints include a main MCP endpoint and a health check.

Available tools

parse_document

Parse a document using Upstage AI's document digitization API. Supports formats: PDF, JPEG, PNG, TIFF, BMP, GIF, WEBP.

extract_information

Extract structured information from documents using Upstage Universal Information Extraction. Supports formats including JPEG, PNG, BMP, PDF, TIFF, HEIC, DOCX, PPTX, XLSX. Can auto-generate a schema if none is provided.

generate_schema

Generate an extraction schema for a document using Upstage AI's schema generation API. Returns a readable schema and a schema_json string for immediate use.

classify_document

Classify a document into predefined categories using Upstage AI's classification API. Supports default categories and user-defined custom schemas.