softkad-mcp

MCP server for APIDIAN 2026 — Softkad's DIAN UBL 2.1 e-invoicing service (Colombia).

Connect your AI assistant to the APIDIAN API to:

• Emit electronic invoices, credit notes, debit notes
• Manage companies, certificates, and resolutions
• Query documents, customers, and DIAN tables
• Download XML/PDF files and check DIAN status

Client	Mode	Config file	Section
Claude Desktop	stdio	claude_desktop_config.json	here
ChatGPT Desktop	stdio	mcp.json	here
Cursor	SSE	Settings → MCP	here
Claude Code	stdio	.mcp.json	here
Cline	stdio	cline_mcp_settings.json	here
VS Code (Copilot)	stdio	settings.json	here
Windsurf	stdio	config.json	here

---

Prerequisites

• uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh)
• An APIDIAN company token (obtained by registering a company in the platform)

---

Quick start — Claude Desktop

macOS: paste into ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: paste into %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ]
    }
  }
}

Replace TU_TOKEN_AQUI with your APIDIAN company token. Restart Claude Desktop completely (Cmd+Q → reopen).

Alternative: token via environment variable (more secure)

{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--no-verify-ssl"
      ],
      "env": {
        "APIDIAN_MCP_TOKEN": "TU_TOKEN_AQUI"
      }
    }
  }
}

---

Quick start — ChatGPT Desktop

macOS: paste into ~/Library/Application Support/OpenAI/ChatGPT/mcp.json

Windows: paste into %APPDATA%\OpenAI\ChatGPT\mcp.json

{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ]
    }
  }
}

---

Quick start — Claude Code

Claude Code runs in your terminal and supports MCP via .mcp.json in the project root.

Create .mcp.json in any project directory (or ~/.mcp.json for global):

{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ]
    }
  }
}

Run claude from that directory. Type /mcp to verify the server loaded.

---

Quick start — Cline (VS Code extension)

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Windows: %USERPROFILE%\AppData\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "mcpServers": [
    {
      "name": "softkad-apidian",
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ],
      "description": "APIDIAN DIAN e-invoicing"
    }
  ]
}

Restart VS Code after saving.

---

Quick start — VS Code (GitHub Copilot)

macOS / Windows / Linux: settings.json (Ctrl+Shift+P → "Preferences: Open Settings JSON")

{
  "github.copilot.chat.mcpServers": [
    {
      "name": "softkad-apidian",
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ]
    }
  ]
}

Requires VS Code 1.96+ and GitHub Copilot Chat extension.

---

Quick start — Windsurf

macOS: ~/.config/windsurf/config.json

Windows: %APPDATA%\Windsurf\config.json

{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ]
    }
  }
}

---

Quick start — Cursor (SSE direct)

Cursor supports SSE directly via the UI:

1. Open Cursor Settings → Features → MCP
2. Click + Add New MCP Server
3. Choose SSE type
4. Enter the URL: https://apidian-mcp.softkad.co/sse?token=TU_TOKEN_AQUI
5. Name it softkad-apidian and save

No JSON file editing needed. The token goes directly in the URL query string.

---

Summary of config file locations

Client	macOS / Linux	Windows
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	%APPDATA%\Claude\claude_desktop_config.json
ChatGPT Desktop	~/Library/Application Support/OpenAI/ChatGPT/mcp.json	%APPDATA%\OpenAI\ChatGPT\mcp.json
Claude Code	./.mcp.json or ~/.mcp.json	same
Cline	~/.config/Code/User/.../cline_mcp_settings.json	%APPDATA%\Code\User\...\cline_mcp_settings.json
VS Code Copilot	settings.json (UI or file)	same
Windsurf	~/.config/windsurf/config.json	%APPDATA%\Windsurf\config.json
Cursor	UI only (SSE)	UI only (SSE)

---

Available tools

Configuration

• apidian_company — Register / update a company (returns token on creation)
• apidian_company_get — Query a company by NIT
• apidian_certificate_upload — Upload digital certificate .p12
• apidian_register_software — Register billing software
• apidian_create_resolution — Create a resolution

Catalog & Query

• apidian_documents_list — List documents by date/search
• apidian_customers_list / apidian_customer_get / apidian_customer_search
• apidian_items_list / apidian_item_get
• apidian_payment_forms / apidian_payment_methods — DIAN tables
• apidian_information — Query DIAN taxpayer info (RUT)
• apidian_download — Download XML / PDF

Emission

• apidian_invoice — Sales invoice
• apidian_credit_note / apidian_debit_note
• apidian_support_document / apidian_eqdoc
• apidian_payroll — Payroll document
• apidian_invoice_mandate — Invoice with mandate (factoring)

Status

• apidian_status_zip — Query by ZIP_KEY
• apidian_status_document — Query by CUFE/CUNE
• apidian_events_document — List registered events

Auxiliary

• apidian_next_consecutive — Next consecutive number
• apidian_whatsapp_send — Send WhatsApp messages

---

Troubleshooting

Symptom	Cause	Fix
softkad-mcp-bridge was not found	Missing --from softkad-mcp	Add it to args
falta el token	No --token or APIDIAN_MCP_TOKEN	Add --token or set env
SSL: CERTIFICATE_VERIFY_FAILED	Let's Encrypt cert not trusted	Add --no-verify-ssl
Server not showing in Claude	Claude not restarted	Close fully (Cmd+Q) and reopen
"Token no válido"	Token expired	Regenerate via company registration

---

Developer documentation

For local development, testing, and server deployment: 📖 Full README on GitHub

---

Softkad — softkad.com