Suporta MCP Server

Connect Claude Code to your Suporta helpdesk — manage tickets, search, and post replies directly from your editor.

Works with any project (Laravel, Vue, React, Node, etc.).

Quick Setup (2 minutes)

1. Generate an API Token

1. Open your Suporta instance (e.g. https://bitpeak.suportahub.com)
2. Go to Settings → API Tokens
3. Click Generate New Token
4. Enter a name (e.g. Claude MCP)
5. Select the projects you want Claude to access
6. Click Generate and copy the token immediately — it's shown only once

2. Add to your project

Create .mcp.json in your project root:

{
	"mcpServers": {
		"suporta": {
			"command": "npx",
			"args": ["-y", "suporta-mcp-server"],
			"env": {
				"SUPORTA_URL": "https://your-tenant.suportahub.com",
				"SUPORTA_TOKEN": "your-api-token-here"
			}
		}
	}
}

3. Restart Claude Code

After saving .mcp.json, restart Claude Code (or run /mcp to reload servers). Verify with:

"who am I on Suporta?"

Claude should respond with your name and role. That's it — you're connected.

Available Tools

| Tool | Description | Example prompt | | ------------------- | ----------------------------------------- | --------------------------------------------------------- | | who-am-i | Verify your connection | "who am I on Suporta?" | | list-projects | List all accessible projects | "show my projects" | | get-ticket | Fetch ticket details by slug or URL | "get ticket 1035-bug-ticket" or paste the ticket URL | | list-my-tickets | List your assigned tickets | "show my open tickets" | | search-tickets | Search by keyword | "search for tickets about login" | | create-ticket | Create a new ticket | "create a P1 ticket in project bitpeak about login bug" | | update-ticket | Update status, priority, assignees, etc. | "set ticket 1035-bug-ticket to Closed" | | post-ticket-reply | Post a reply (internal or client-visible) | "post an internal note on ticket 1035-bug-ticket" | | link-branch | Attach a git branch to a ticket | "link branch fix/icons to ticket 1484" | | unlink-branch | Remove a repository's branch | "unlink the bitpeak-v3 branch from ticket 1484" | | link-pull-request | Attach a pull request to a ticket | "link this PR to ticket 1484" | | unlink-pull-request | Remove a pull request | "unlink that PR from ticket 1484" |

Usage Examples

Fetch a ticket from URL:

Paste https://bitpeak.suportahub.com/ticket/1035-bug-ticket and Claude will extract the slug and fetch details.

Filter your tickets:

"show my overdue tickets" "list my open tickets due this week"

Create a ticket:

"create a ticket in project bitpeak: Login page returns 500 on invalid email"

Update a ticket:

"set ticket 1035-bug-ticket priority to P1 and assign to user 14" "close ticket 1035-bug-ticket"

Implement a ticket:

"fetch ticket 1035-bug-ticket and implement it"

Claude will read the ticket, analyze the codebase, create a branch, implement the changes, and post a summary back on the ticket.

Post an internal note:

"post an internal note on ticket 1035-bug-ticket saying the fix is deployed"

Link a branch and a pull request:

"link branch fix/icon-font-flash to ticket 1484" "link https://bitbucket.org/bitpeak_code/bitpeak-v3/pull-requests/11 to ticket 1484"

These fill the same sidebar blocks the web app shows, and they satisfy the board lanes that gate on a branch or a pull request.

Three things worth knowing:

• They add, they do not replace. The underlying API takes the complete list, so linking one pull request would normally unlink the rest. These tools read the current list first and merge, keeping what is there. Pass replace_all: true when you really do want only the new one.
• A repository holds one branch. Linking a second branch for the same repository replaces the first, and the result says which name it displaced.
• repository_slug is optional when the project maps exactly one Bitbucket repository, which is the usual case. When it maps several, the error lists them.

Both are staff-only (role:admin|support), matching the web sidebar, which has always hidden branches and pull requests from clients.

Multiple Projects / Tenants

Each project gets its own .mcp.json with its own token and URL. This means:

• Project A → connects to https://clienta.suportahub.com with token scoped to Project A's projects
• Project B → connects to https://clientb.suportahub.com with a different token

Tokens are scoped to specific projects at generation time, so each developer only sees what they need.

Troubleshooting

"Not connected" error

• Check that SUPORTA_URL and SUPORTA_TOKEN are set in .mcp.json
• Make sure the token hasn't been deleted in Settings → API Tokens
• Restart Claude Code after changing .mcp.json

"API 401" error

• Your token is invalid or expired. Generate a new one in Settings → API Tokens

Tools not showing up

• Run /mcp in Claude Code to check server status
• Verify node is available in your PATH
• Make sure you have Node.js 18+ installed

CI/CD: Auto-publish to npm on main

This repo includes GitHub Actions workflow publish-npm.yml that runs on every push to main.

What it does:

• Installs dependencies
• Bumps patch version automatically
• Commits the version bump back to main
• Publishes the new version to npm

Required GitHub secret

Add this repository secret in GitHub:

• Name: NPM_TOKEN
• Value: your npm access token (Automation or Publish token)

GitHub path: Settings -> Secrets and variables -> Actions -> New repository secret