SpecWeave MCP Integration Guide

Connect Claude Code and other AI tools to your SpecWeave requirements

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI assistants like Claude Code to access your data and tools. With SpecWeave's MCP integration, you can:

Query requirements, features, and tasks using natural language
Create and update items directly from your code editor
Search across your entire requirements hierarchy
Track recent activity and changes
Manage assumptions, open questions, and user stories

Quick Start

Prerequisites

A SpecWeave account
Claude Code or another MCP-compatible client
Node.js 18 or later (for stdio transport)

Step 1: Create an MCP Access Token

Log in to SpecWeave
Navigate to Settings → MCP Tokens
Click "Create MCP Token"
Select the Application you want to access (e.g., "FabWise", "SpecWeave")
Choose the scopes you need:
- mcp:read - View requirements data
- mcp:create - Create new items
- mcp:update - Update existing items
- mcp:delete - Delete items
Click "Generate Token"
Copy the token - you won't be able to see it again!

Step 2: Choose Your Integration Method

SpecWeave MCP supports two integration methods:

Method	Scope	Best For	Setup Time
HTTP	User-level (global)	Quick start, personal dev, testing	5 minutes
stdio (NPM)	Project-level	Team projects, production, critical apps	7 minutes

Key Difference: HTTP is configured globally on your machine (all projects share one token). stdio is configured per-project (each project has its own token with specific permissions).

Security Recommendation: Use stdio for production and team projects where you need granular access control and token isolation. Use HTTP for personal development and quick testing.

Method 1: stdio Transport (Project-Level, Recommended for Teams)

Why Use stdio?

Security Benefits:
- ✓ Token per project - Each project has its own isolated token
- ✓ Granular access - Scope tokens to specific Applications (e.g., FabWise vs SpecWeave)
- ✓ Team sharing - Configuration committed to git, tokens via environment variables
- ✓ Easy revocation - Revoke one project's access without affecting others
- ✓ Audit trail - Track which token is used in which project

Comparison with HTTP:
- HTTP = One token for all your projects globally (security risk)
- stdio = One token per project (secure isolation)

For Claude Code

Create or edit .mcp.json in your project directory:

{
  "mcpServers": {
    "specweave": {
      "command": "npx",
      "args": ["-y", "@specweave/mcp-client"],
      "env": {
        "SPECWEAVE_TOKEN": "paste_your_token_here"
      }
    }
  }
}

Restart Claude Code
Run /mcp to connect
Test the connection:
```

list all products in my application
```

For Other MCP Clients

The stdio transport is compatible with any MCP client that supports the command configuration. Replace the .mcp.json path with your client's configuration file location.

Environment Variables (Optional)

You can customize the MCP client behavior with these environment variables:

SPECWEAVE_TOKEN (required) - Your access token
SPECWEAVE_URL (optional) - Custom endpoint (default: https://specweave.ai/mcp)

Method 2: HTTP API (User-Level, Quick Start)

Why Use HTTP?

Advantages:
- ✓ Fastest setup - Works in 5 minutes with claude mcp add
- ✓ No dependencies - No Node.js or NPM required
- ✓ Direct connection - Lower latency, simpler debugging

Trade-offs:
- ⚠️ User-level only - Cannot be scoped to individual projects
- ⚠️ Shared token - Same token used across ALL your projects
- ⚠️ Security risk - If compromised, affects all projects using SpecWeave MCP
- ⚠️ Team setup - Each developer must configure manually

Best for: Personal development, prototyping, quick testing

Not recommended for: Production apps, team projects, security-sensitive work

For Claude Code (Quick Setup)

⚠️ Security Note: This creates a global configuration that applies to ALL Claude Code projects on your machine.

# Add SpecWeave MCP globally
claude mcp add specweave https://specweave.ai/mcp \
  --transport http \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

After running this command:
1. Restart Claude Code
2. Run /mcp to connect
3. The connection will be available in all Claude Code projects

To remove the global connection:
bash claude mcp remove specweave

Direct HTTP Integration

The SpecWeave MCP server accepts JSON-RPC 2.0 requests via HTTPS.

Endpoint: https://specweave.ai/mcp

Example Request:

curl -X POST https://specweave.ai/mcp \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "list_products",
        "description": "List all products within the current application",
        "inputSchema": {
          "type": "object",
          "properties": {
            "functional_area_id": {
              "type": "string",
              "description": "Filter by functional area ID"
            }
          }
        }
      }
    ]
  }
}

Using the HTTP API

Initialize the connection:

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

List available tools:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Call a tool:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_products",
    "arguments": {
      "functional_area_id": "abc-123"
    }
  }
}

Available Tools

SpecWeave MCP provides 37 tools organized by category:

Requirements Management

Functional Areas: list_functional_areas, create_functional_area, update_functional_area, delete_functional_area
Products: list_products, create_product, update_product, delete_product
Features: list_features, create_feature, update_feature, delete_feature
Tasks: list_tasks, create_task, update_task, delete_task

Documentation

Assumptions: list_assumptions, create_assumption, update_assumption, validate_assumption, invalidate_assumption
Open Questions: list_open_questions, create_open_question, update_open_question, answer_question, defer_question
User Stories: list_user_stories, create_user_story, update_user_story, delete_user_story
Out of Scope: list_out_of_scope_items, create_out_of_scope_item, update_out_of_scope_item, reassess_scope_item

Hierarchy Navigation: get_children, get_ancestors, get_related
Search: search_hierarchy
Activity: get_recent_activity

Collaboration

Comments: list_comments, create_comment, update_comment, delete_comment

Bulk Operations

Status Updates: bulk_update_status

Application Scoping

Important: Each access token is scoped to a single Application (e.g., "FabWise" or "SpecWeave").

When you create a token, you select which Application it can access. The token cannot access data from other Applications in your account.

Example:
- Token for "FabWise" ✓ Can access FabWise products/features
- Token for "FabWise" ✗ Cannot access SpecWeave products/features

To access multiple applications, create separate tokens for each.

Troubleshooting

Connection Issues

Problem: Claude Code shows "needs authentication"

Solution:
- Ensure you're using the stdio transport (npx), not HTTP
- Verify your token is in the .mcp.json file
- Restart Claude Code after configuration changes

Problem: "Invalid or expired token"

Solutions:
1. Check your token hasn't been revoked in Settings → MCP Tokens
2. Verify you copied the entire token (no extra spaces)
3. Create a new token if needed

Problem: NPM package not found

Solution:
```bash

Manually install the package

npm install -g @specweave/mcp-client

Or clear npm cache

npm cache clean --force
npx -y @specweave/mcp-client
```

Problem: Node.js version error

Solution:
```bash

Check Node.js version

node --version

Must be 18 or higher

Upgrade if needed: https://nodejs.org


### Usage Issues

**Problem**: "No products found" when you know products exist

**Solution**:
- Verify your token is scoped to the correct Application
- Check the Application selection when you created the token
- Create a new token with the correct Application selected

---

**Problem**: Cannot create items (403 Forbidden)

**Solution**:
- Ensure your token has the required scopes:
  - `mcp:create` for creating items
  - `mcp:update` for updating items
  - Check token scopes in Settings → MCP Tokens
- Create a new token with appropriate scopes if needed

---

**Problem**: Slow responses

**Causes**:
- Large datasets (hundreds of items)
- Network latency
- Database performance

**Solutions**:
- Use filters to narrow queries (e.g., `list_features` with `product_id`)
- Limit results where possible
- Contact support if consistently slow

## Security Best Practices

### Token Management

1. **Treat tokens like passwords**
   - Never commit tokens to version control
   - Use environment variables or secure vaults
   - Rotate tokens regularly

2. **Use minimum required scopes**
   - Only request scopes you actually need
   - Read-only workflows should use `mcp:read` only
   - Available scopes: `mcp:read`, `mcp:create`, `mcp:update`, `mcp:delete`

3. **Create separate tokens per integration**
   - One token for Claude Code
   - Different token for CI/CD
   - Easy to revoke specific integrations

4. **Revoke unused tokens**
   - Go to Settings → MCP Tokens
   - Revoke tokens you're no longer using

### Project Configuration

**Bad**: Commit tokens to Git
```json
{
  "mcpServers": {
    "specweave": {
      "env": {
        "SPECWEAVE_TOKEN": "actual_token_here"  ❌ DON'T DO THIS
      }
    }
  }
}

Good: Use environment variable references
json { "mcpServers": { "specweave": { "env": { "SPECWEAVE_TOKEN": "${SPECWEAVE_TOKEN}" ✓ Reference from environment } } } }

Then set the actual token in your shell:
bash export SPECWEAVE_TOKEN="your_token_here"

FAQ

General

Q: What is the difference between stdio and HTTP transports?

A: stdio is the standard MCP transport using stdin/stdout (recommended for Claude Code). HTTP is direct API access for custom integrations. Both use the same authentication and provide the same tools.

Q: Can I use the same token in multiple projects?

A: Yes! The token is account-level and application-scoped. You can use it in multiple projects that need access to the same Application.

Q: Do tokens expire?

A: By default, tokens expire after 90 days. You can see expiration dates in Settings → MCP Tokens.

Q: Can I create tokens via API?

A: Currently, tokens must be created through the web UI. API-based token creation is planned for a future release.

Claude Code Specific

Q: Where should I put the .mcp.json file?

A: In your project root directory. This makes the MCP connection available for that specific project.

Q: Can I have project-level and global MCP connections?

A: Yes! Project .mcp.json and global ~/.claude/mcp.json configurations are merged. Project settings override global settings.

Q: Why does Claude Code still ask me to authenticate?

A: This happens when using HTTP transport. Make sure you're using the stdio transport with "command": "npx" in your .mcp.json.

Technical

Q: What's the rate limit?

A: Currently no enforced rate limits. Fair use policy applies - excessive API usage may be throttled.

Q: Can I use SpecWeave MCP with other AI assistants?

A: Yes! Any MCP-compatible client can use SpecWeave MCP. The protocol is an open standard.

Q: Does SpecWeave MCP support WebSockets?

A: Not yet. Currently supports HTTP JSON-RPC and stdio transports. WebSocket support is planned.

Q: Can I get real-time updates when requirements change?

A: Not currently. You need to re-query to get updated data. Real-time notifications are planned for a future release.

Example Use Cases

Use Case 1: Requirements Review in Claude Code

You: Review all open questions for the User Authentication feature

Claude: I'll check the open questions for the User Authentication feature.
[Uses list_open_questions tool]

Found 3 open questions:
1. [High Priority] Should we support SSO? - Status: Open
2. [Medium] Max password length? - Status: Open
3. [Low] Remember me duration? - Status: Answered (30 days)

Would you like me to help draft answers for the open questions?

Use Case 2: Creating Tasks from Code Review

You: I found a security issue in the login flow. Create a task to add
     rate limiting to the authentication endpoint.

Claude: I'll create a task for adding rate limiting to authentication.
[Uses create_task tool]

Created task AUTH-124: "Add rate limiting to authentication endpoint"
- Feature: User Authentication
- Status: todo
- Complexity: moderate
- Description: Implement rate limiting to prevent brute force attacks...

Would you like me to add acceptance criteria or link related tasks?

Use Case 3: Generating Documentation

You: Generate a summary of all completed features in the last sprint

Claude: I'll fetch completed features from the last sprint.
[Uses list_features with status filter]
[Uses get_recent_activity]

Sprint Summary - Last 7 Days:
✓ 5 features completed
✓ 12 tasks closed
✓ 3 user stories implemented

Completed Features:
1. Social Login Integration (AUTH-PRD-001)
2. Password Reset Flow (AUTH-PRD-002)
...

Would you like me to format this as a release notes document?

Getting Help

Support Channels

Documentation: https://docs.specweave.ai
Email Support: support@specweave.ai
GitHub Issues: SpecWeave MCP Client

Reporting Issues

When reporting issues, please include:

Transport method (stdio or HTTP)
Client (Claude Code version, custom client, etc.)
Error messages (full error text)
Steps to reproduce
Expected vs actual behavior

Feature Requests

We're actively developing SpecWeave MCP! Request features at:
- Email: product@specweave.ai
- In-app: Settings → Feedback

Changelog

Version 1.0.0 (2025-10-30)

Initial release:
- OAuth 2.1 authentication
- Application-scoped access tokens
- stdio transport via NPM package
- HTTP JSON-RPC API
- 37 MCP tools across 9 categories
- Multi-tenancy isolation
- Claude Code integration

Ready to get started? Create your first MCP token →